windows.texi 156 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@setfilename ../../info/windows
Glenn Morris's avatar
Glenn Morris committed
7 8 9
@node Windows, Frames, Buffers, Top
@chapter Windows

10 11 12 13
This chapter describes the functions and variables related to Emacs
windows.  @xref{Frames}, for how windows are assigned an area of screen
available for Emacs to use.  @xref{Display}, for information on how text
is displayed in windows.
Glenn Morris's avatar
Glenn Morris committed
14 15 16

@menu
* Basic Windows::           Basic information on using windows.
17 18 19
* Windows and Frames::      Relating windows to the frame they appear on.
* Window Sizes::            Accessing a window's size.
* Resizing Windows::        Changing the sizes of windows.
Glenn Morris's avatar
Glenn Morris committed
20 21 22 23 24
* 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.
25
* Switching Buffers::       Higher-level functions for switching to a buffer.
Glenn Morris's avatar
Glenn Morris committed
26
* Choosing Window::         How to choose a window for displaying a buffer.
27 28
* Display Action Functions:: Subroutines for @code{display-buffer}.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
29
* Window History::          Each window remembers the buffers displayed in it.
Glenn Morris's avatar
Glenn Morris committed
30
* Dedicated Windows::       How to avoid displaying another buffer in
31
                              a specific window.
Glenn Morris's avatar
Glenn Morris committed
32
* Window Point::            Each window has its own location of point.
Martin Rudalics's avatar
Martin Rudalics committed
33 34
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
Glenn Morris's avatar
Glenn Morris committed
35 36 37 38 39
* 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.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Configurations::   Saving and restoring the state of the screen.
Martin Rudalics's avatar
Martin Rudalics committed
40
* Window Parameters::       Associating additional information with windows.
Glenn Morris's avatar
Glenn Morris committed
41 42 43 44 45
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
@end menu

46

Glenn Morris's avatar
Glenn Morris committed
47 48 49 50
@node Basic Windows
@section Basic Concepts of Emacs Windows
@cindex window

51 52 53 54
A @dfn{window} in Emacs is the physical area of the screen in which a
buffer is displayed, see @ref{Buffers}.  The term is also used to refer
to a Lisp object that represents that screen area in Emacs Lisp.  It
should be clear from the context which is meant.
Glenn Morris's avatar
Glenn Morris committed
55 56

@cindex multiple windows
57 58 59 60 61 62 63 64
  Emacs groups windows into frames; see @ref{Frames}.  Each frame always
contains at least one window, but you can subdivide it into multiple,
non-overlapping Emacs 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 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.
Glenn Morris's avatar
Glenn Morris committed
65

66 67
@cindex terminal screen
@cindex screen of terminal
Glenn Morris's avatar
Glenn Morris committed
68 69 70
  The meaning of ``window'' in Emacs is similar to what it means in the
context of general-purpose window systems such as X, but not identical.
The X Window System places X windows on the screen; Emacs uses one or
71 72 73
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.
Glenn Morris's avatar
Glenn Morris committed
74 75 76 77 78

@cindex tiled windows
  Most window systems support arbitrarily located overlapping windows.
In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
together they fill the whole screen or frame.  Because of the way in
Martin Rudalics's avatar
Martin Rudalics committed
79 80 81
which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
them (@pxref{Resizing Windows}), not all conceivable tilings of windows
on an Emacs frame are actually possible.
Glenn Morris's avatar
Glenn Morris committed
82

83 84 85 86 87 88 89 90
  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, even though the Lisp object representing it
might be still referenced from other Lisp objects; see @ref{Deleting
Windows}.  Restoring a saved window configuration is the only way for a
window no longer on the screen to come back to life; see @ref{Window
Configurations}.

Glenn Morris's avatar
Glenn Morris committed
91
@defun windowp object
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
This function returns @code{t} if @var{object} is a window, @code{nil}
otherwise.  It can return @code{t} if @var{object} denotes a window that
has been deleted.
@end defun

@cindex live windows
@cindex internal windows
   For historical reasons a window is considered @dfn{live} if and only
if it currently displays a buffer; see @ref{Buffers and Windows}.  In
order to show multiple windows within one and the same frame, Emacs
organizes them in form of a tree called window tree; see @ref{Windows
and Frames}.  The internal nodes of a window tree are called internal
windows and are not considered live.  The leaf nodes of a window tree
constitute the windows displaying buffers and only they will be called
live here.

@defun window-live-p object
This function returns @code{t} if @var{object} is a live window and
@code{nil} otherwise.  A live window is a window that displays a buffer.
@end defun

@defun window-any-p object
This function returns @code{t} if @var{object} denotes a live or an
internal window and @code{nil} otherwise.  In particular, this function
returns @code{nil} if @var{object} is a window that has been
deleted.
@end defun

@cindex selected window
In each frame, at any time, one and only one window is designated as
@dfn{selected within the frame}.  Also, at any time, one frame is the
selected frame (@pxref{Input Focus}).  The window selected within the
selected frame is the @dfn{selected window}.

   The selected window is always a live window.  Its buffer is usually
the current buffer (except when @code{set-buffer} has been used); see
@ref{Current Buffer}.

@defun selected-window
This function returns the selected window.  This is the window in which
the cursor for selected windows (@pxref{Cursor Parameters}) appears and
to which many commands apply.
@end defun

The window handling functions can be roughly grouped into functions
operating on live windows only and functions that accept any window as
argument.  Many of these functions accept as argument the value
@code{nil} to specify the selected window.  The two functions below can
be used to ``normalize'' arguments specifying windows in a uniform
manner.

@defun window-normalize-any-window window
This function returns the normalized value for @var{window} which can be
any window that has not been deleted.  More precisely, if @var{window}
is @code{nil}, it returns the selected window.  If @var{window} denotes
a live or internal window, it returns that window.  Otherwise, this
function signals an error.
@end defun

@defun window-normalize-live-window window
This functions returns the normalized value for a live window
@var{window}.  More precisely, if @var{window} is @code{nil}, it returns
the selected window.  If @var{window} is a live window, it returns that
window.  Otherwise, this function signals an error.
@end defun


@node Windows and Frames
@section Windows and Frames

Each window is part of one and only one frame (@pxref{Frames}); you can
get that frame with the function described next.

@defun window-frame window
This function returns the frame that @var{window} is on.  The argument
@var{window} can be any window and defaults to the selected one.
@end defun

The following function returns a list of all live windows on a specific
frame.

@defun window-list &optional frame minibuf window
This function returns a list of @var{frame}'s live windows, starting
with @var{window}.  The optional argument @var{frame} has to denote a
live frame and defaults to the selected frame.  The optional argument
@var{window} has to denote a live window on the frame specified by
@var{frame} and defaults to the selected one.

The argument @var{minibuf} specifies if the minibuffer window shall be
included in the return value.  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 only if it is active.
If @var{minibuf} is neither @code{nil} nor @code{t}, the result never
includes the minibuffer window.
@end defun

@cindex window tree
Windows within one and the same frame are organized in form of a tree
called @dfn{window tree}.  The leaf nodes of a window tree constitute
the windows visible to the user.  These are the windows associated with
buffers and are usually called live windows.  The internal nodes of a
window tree are needed for finding, traversing and displaying the live
windows.

   A minibuffer window (@pxref{Minibuffer Windows}) is not considered
part of its frame's window tree unless the frame is a minibuffer-only
frame.  Most functions covered in this section accept, however, the
minibuffer window as argument.  Also, the minibuffer window is listed by
the function @code{window-tree} described at the end of this section.

   A window tree is rooted at the root window of its frame.

@defun frame-root-window &optional frame-or-window
This function returns the root window of @var{frame-or-window}.  The
argument @var{frame-or-window} has to denote either a window or a frame
and defaults to the selected frame.  If @var{frame-or-window} denotes a
window, the return value is the root window of that window's frame.
This function always returns a window; a live window if the frame
specified by @var{frame-or-window} contains no other live windows and an
internal window otherwise.
@end defun

@cindex subwindow
All other windows of a frame with the exception of the minibuffer window
are subwindows of the frame's root window.  A window is considered a
@dfn{subwindow} of another window if it occupies a part of that other
window's screen area.

The functions described next allow to access the members of a window
tree and take an arbitrary window as argument.

@cindex parent window
@defun window-parent &optional window
Return @var{window}'s parent in the window tree.  The optional argument
@var{window} can denote an arbitrary window and defaults to the selected
one.  The return value is @code{nil} if @var{window} is a minibuffer
window or the root window of its frame and an internal window otherwise.
@end defun

@cindex child window
   Parent windows do not appear on the screen.  The screen area of a
parent window is the rectangular part of the window's frame occupied by
the window's @dfn{child windows}, that is, the set of windows having
that window as their parent.  Each parent window has at least two child
windows, so there are no ``Matryoshka'' windows.  Minibuffer windows do
not have child windows.

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
The children of any parent window form either a vertical or a horizontal
combination of windows.  A @dfn{vertical combination} is a set of
windows arranged one above each other.  A @dfn{horizontal combination}
is a set of windows arranged side by side.  Consider the frame shown
below (for simplicity we assume that the frame does not contain a
minibuffer window):

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      ||| ___________  ___________ |||
    ||      ||||           ||           ||||
    ||      ||||           ||           ||||
    ||      ||||_____W6____||_____W7____||||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

The root window of the frame is @code{W1}---a horizontal combination of
the live window @code{W2} and the internal window @code{W3}.  Hence
@code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)}
and @code{(window-parent W3)} are both @code{W1}.

   The internal window @code{W3} is a vertical combination of @code{W4}
and the live window @code{W5}.  The internal window @code{W4} is a
horizontal combination of the live windows @code{W6} and @code{W7}.  The
windows you can actually see on the screen are @code{W2}, @code{W5},
@code{W6} and @code{W7}.

   For any parent window, the first child window can be retrieved by the
functions given next.

@defun window-top-child &optional window
This function returns @var{window}'s first vertical child window.  The
optional argument @var{window} can be an arbitrary window and defaults
to the selected one.  The return value is @code{nil} if @var{window} is
a live window or its children form a horizontal combination.  In the
example above @code{(window-top-child W3)} is @code{W4} while
@code{(window-top-child W4)} is @code{nil}.
@end defun

@defun window-left-child &optional window
This function returns @var{window}'s first horizontal child window.  The
optional argument @var{window} can be an arbitrary window and defaults
to the selected one.  The return value is @code{nil} if @var{window} is
a live window or its children form a vertical combination.  In the
example above @code{(window-left-child W4)} is @code{W6} while
297
@code{(window-left-child W3)} is @code{nil}.
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 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 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 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 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 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 682 683 684 685 686 687 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 714 715 716 717 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 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793
@end defun

@defun window-child window
This function return @var{window}'s first child window.  The return
value is @code{nil} if @var{window} is a live window.  In the example
above @code{(window-child W3)} is @code{W4} while @code{(window-child
W4)} is @code{W6}.
@end defun

The following function is useful to determine whether a window is part
of a vertical or horizontal combination.

@defun window-iso-combined-p &optional window horizontal
This function returns non-@code{nil} if and only if @var{window} is
vertically combined.  The argument @var{window} can specify any window
and defaults to the selected one.  The actual return value is the first
vertical child of window.

If the optional argument @var{horizontal} is non-@code{nil}, this means
to return non-@code{nil} if and only if @var{window} is horizontally
combined.  In this case, the return value is the first horizontal child
of window.
@end defun

@cindex sibling window
For any window that is part of a combination, the other windows in that
combination are called the window's @dfn{siblings}.  The only windows
that do not have siblings are root windows of frames and minibuffer
windows.  A window's siblings can be retrieved with the following two
functions.

@defun window-next-sibling &optional window
This function returns @var{window}'s next sibling.  The optional
argument @var{window} can be an arbitrary window and defaults to the
selected window.  It returns @code{nil} if @var{window} is the last
child of its parent.  In our example @code{(window-next-sibling W2)} is
@code{W3} while @code{(window-next-sibling W3)} is @code{nil}.
@end defun

@defun window-prev-sibling &optional window
This function returns @var{window}'s previous sibling.  The optional
argument @var{window} can be an arbitrary window and defaults to the
selected window.  It returns @code{nil} if @var{window} is the first
child of its parent. In our example @code{(window-prev-sibling W3)} is
@code{W2} and @code{(window-prev-sibling W2)} is @code{nil}.
@end defun

The functions @code{window-next-sibling} and @code{window-prev-sibling}
should not be confused with the functions @code{next-window} and
@code{previous-window} which respectively return the next and previous
window in the cyclic ordering of windows, see @ref{Cyclic Window
Ordering}.

   In order to find the first live window on a frame, the following
function can be used.

@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
frame specified by @var{frame-or-window}.  The argument
@var{frame-or-window} must denote a window or a live frame and defaults
to the selected frame.  If @var{frame-or-window} specifies a window,
this function returns the first window on that window's frame.  Under
the assumption that the frame from our canonical example is selected
@code{(frame-first-window)} returns @code{W2}.
@end defun

You can get the window tree of a frame with the following function.

@cindex window tree
@defun window-tree &optional frame
This function returns the window tree for frame @var{frame}.  The
optional argument @var{frame} must be a live frame and defaults to the
selected one.

The return value is a list of the form @code{(@var{root} @var{mini})},
where @var{root} represents the window tree of the frame's
root window, and @var{mini} is the frame's minibuffer window.

If the root window is live, @var{root} specifies the root window and
nothing else.  Otherwise, @var{root} is a list @code{(@var{dir}
@var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
horizontal combination, and @code{t} for a vertical combination,
@var{edges} gives the size and position of the combination, and the
remaining elements are the child windows.  Each child window may again
be a live window or a list representing a window combination, and so on.
The @var{edges} element is a list @code{(@var{left}@var{ top}@var{
right}@var{ bottom})} similar to the value returned by
@code{window-edges}, see @ref{Coordinates and Windows}.
@end defun


@node Window Sizes
@section Window Sizes
@cindex window size
@cindex size of window

Emacs windows are rectangular.  The structure of a live window can be
roughly sketched as follows:

@smallexample
@group
         _________________________________________ 
      ^ |______________ Header Line_______________| 
      | |LS|LF|LM|                       |RM|RF|RS| ^
      | |  |  |  |                       |  |  |  | |
 Window |  |  |  |       Text Area       |  |  |  | Window
 Total  |  |  |  |     (Window Body)     |  |  |  | Body
 Height |  |  |  |                       |  |  |  | Height
      | |  |  |  |<- Window Body Width ->|  |  |  | |
      | |__|__|__|_______________________|__|__|__| v
      v |_______________ Mode Line _______________|

         <----------- Window Total Width -------->

@end group
@end smallexample

@cindex window body
@cindex body of a window
The text area constitutes the body of the window.  In its most simple
form, a window consists of its body alone.  LS and RS stand for the left
and right scroll bar (@pxref{Scroll Bars}) respectively.  Only one of
them can be present at any time.  LF and RF denote the left and right
fringe, see @ref{Fringes}.  LM and RM, finally, stand for the left and
right display margin, see @ref{Display Margins}.  The header line, if
present, is located above theses areas, the mode line below, see
@ref{Mode Line Format}.

@cindex window height
@cindex total window height
@cindex height of a window
@cindex total height of a window
The @dfn{total height of a window} is specified as the total number of
lines occupied by the window.  Any mode or header line is included in a
window's total height.  For an internal window, the total height is
calculated recursively from the total heights of its child windows.

@cindex window width
@cindex total window width
@cindex width of a window
@cindex total width of a window
The @dfn{total width of a window} denotes the total number of columns of
the window.  Any scroll bar and the column of @samp{|} characters that
separate the window from its right sibling are included in a window's
total width.  On a window-system, fringes and display margins are
included in a window's total width too.  For an internal window, the
total width is calculated recursively from the total widths of its child
windows.

@cindex total size of a window
@cindex total window size
The following function is the standard interface for getting the total
size of any window:

@defun window-total-size &optional window &optional horizontal
This function returns the total number of lines of @var{window}.  The
argument @var{window} can denote any window and defaults to the selected
one.  If @var{window} is live, the return value includes any header or
mode lines of @var{window}.  If @var{window} is internal, the return
value is the sum of the total heights of @var{window}'s child windows
provided these are vertically combined and the height of @var{window}'s
first child if they are horizontally combined.

   If the optional argument @var{horizontal} is non-@code{nil}, this
function returns the total number of columns of @var{window}.  If
@var{window} is live, the return value includes any vertical divider
column or scroll bars of @var{window}.  On a window-system, the return
value includes the space occupied by any margins and fringes of
@var{window} too.  If @var{window} is internal, the return value is the
sum of the total widths of @var{window}'s child windows provided these
are horizontally combined and the width of @var{window}'s first child
otherwise.
@end defun

Alternatively, the following two functions can be used to retrieve
either the total height or the total width of a window:

@defun window-total-height &optional window
This function returns the total number of lines of @var{window}.
@var{window} can be any window and defaults to the selected one.  The
return value includes @var{window}'s mode line and header line, if any.
If @var{window} is internal the return value is the sum of heights of
@var{window}'s child windows for a vertical combination and the height
of @var{window}'s first child otherwise.
@end defun

@defun window-total-width &optional window
This function returns the total number of columns of @var{window}.
@var{window} can be any window and defaults to the selected one.  The
return value includes any vertical dividers or scrollbars of
@var{window}.  On a window-system the return value also includes the
space occupied by any margins and fringes of @var{window}.  If
@var{window} is internal, the return value is the sum of the widths of
@var{window}'s child windows for a horizontal combination and the width
of @var{window}'s first child otherwise.
@end defun

The total height of any window is usually less than the height of the
window's frame, because the latter may also include the minibuffer
window.  Depending on the toolkit in use, the frame height can also
include the menu bar and the tool bar (@pxref{Size and Position}).
Therefore, in general it is not straightforward to compare window and
frame heights.  The following function is useful to determine whether
there are no other windows above or below a specified window.

@cindex full-height window
@defun window-full-height-p &optional window
This function returns non-@code{nil} if there is no other window above
or below @var{window} on the containing frame.  More precisely, this
function returns @code{t} if and only if the total height of
@var{window} equals the total height of the root window (@pxref{Windows
and Frames}) of @var{window}'s frame.  The @var{window} argument may
denote any window and defaults to the selected one.
@end defun

@cindex full-width window
The following function can be used to determine whether there are no
other windows on the left or right of a specified window.

@defun window-full-width-p &optional window
This function returns non-@code{nil} if there are no other windows on
the left or right of @var{window}; @code{nil} otherwise.  More
precisely, this function returns @code{t} if and only if the total width
of @var{window} equals the total width of the root window
(@pxref{Windows and Frames}) of @var{window}'s frame.  The @var{window}
argument may denote any window and defaults to the selected one.
@end defun

@cindex top line of window
@cindex left column of window
  The windows of a frame are unambiguously characterized by the
combination of their top line and left column within that frame.

@defun window-top-line &optional window
This function returns the top line of @var{window}.  The argument
@var{window} can denote any window and defaults to the selected one.
@end defun

@defun window-left-column &optional window
This function returns the left column of @var{window}.  The argument
@var{window} can denote any window and defaults to the selected one.
@end defun

For a frame displaying one window only, that window's top line and left
column are both zero.  When a frame displays a window @var{WB} below a
window @var{WA}, the top line of @var{WB} can be calculated by adding
the total height of @var{WA} to the top line of @var{WA}.  When a frame
displays a window @var{WR} on the right of a window @var{WL}, the left
column of @var{WR} can be calculated by adding the total width of
@var{WL} to the left column of @var{WL}.

@cindex window body height
@cindex body height of a window
The @dfn{body height of a window} is specified as the total number of
lines occupied by the window's text area.  Mode or header lines are not
included in a window's body height.

@cindex window body width
@cindex body width of a window
The @dfn{body width of a window} denotes the total number of columns
occupied by the window's text area.  Scroll bars or columns of @samp{|}
characters that separate side-by-side windows are not included in a
window's body width.

@cindex body size of a window
@cindex window body size
The following functions retrieve height and width of the body of a live
window:

@defun window-body-size &optional window horizontal
This function returns the number of lines of @var{window}'s text area.
@var{window} must be a live window and defaults to the selected one.
The return value does not count any mode or header line of @var{window}.

Optional argument @var{horizontal} non-@code{nil} means to return the
number of columns of @var{window}'s text area.  In this case the return
value does not include any vertical divider or scroll bar owned by
@var{window}.  On a window-system the return value does not include the
number of columns used for @var{window}'s fringes or display margins
either.
@end defun

@defun window-body-height &optional window
This function returns the number of lines of @var{window}'s body.
@var{window} must be a live window and defaults to the selected one.

The return value does not include @var{window}'s mode line and header
line, if any.  If a line at the bottom of the window is only partially
visible, that line is included in the return value.  If you do not
want to include a partially visible bottom line in the return value,
use @code{window-text-height} instead.
@end defun

@defun window-body-width &optional window
This function returns the number of columns of @var{window}'s body.
@var{window} must be a live window and defaults to the selected one.

The return value does not include any vertical dividers or scroll bars
owned by @var{window}.  On a window-system the return value does not
include the number of columns used for @var{window}'s fringes or
display margins either.
@end defun

The following functions have been used in earlier versions of Emacs.
They are still supported but due to the confusing nomenclature they
should not be used any more in future code.

@defun window-height &optional window
This function is an alias for `window-total-height', see above.
@end defun

@defun window-width &optional window
This function is an alias for `window-body-width', see above.
@end defun

@cindex minimum window size
  The following two options constrain the sizes of windows to a minimum
height and width.  Their values are honored when windows are split
(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).  Any
request to make a window smaller than specified here will usually result
in an error.

@defopt window-min-height
The value of this variable specifies how short a window may be.  The
value is measured in line units and has to account for any header or
mode line.  The default value for this option is @code{4}.  Values less
than @code{1} are ignored.
@end defopt

@defopt window-min-width
The value of this variable specifies how narrow a window may be.  The
value is measured in characters and includes any margins, fringes,
scroll bar and vertical divider column.  The default value for this
option is @code{10}.  A value less than @code{2} is ignored.
@end defopt

Applications should not rebind these variables.  To shrink a specific
window to a height or width less than the one specified here, they
should rather invoke @code{window-resize} (@pxref{Resizing Windows})
with a non-@code{nil} @var{ignore} argument.  The function
@code{split-window} (@pxref{Splitting Windows}) can make a window
smaller than specified here by calling it with a non-@code{nil}
@var{size} argument.  Interactively, the values specified here cannot be
overridden.

   Earlier versions of Emacs could delete a window when its size dropped
below @code{window-min-height} or @code{window-min-width}.  As a rule,
the current version of Emacs does no more delete windows by side-effect.
The only exception to this rule are requests to resize a frame which may
implicitly delete windows when they do not fit on the frame any more,
see @ref{Size and Position}.

   The size of a window can be fixed which means that it cannot be split
(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).

@cindex fixed-size window
@defvar window-size-fixed
If this variable is non-@code{nil}, in a given buffer, then the size of
any window displaying that buffer remains fixed unless you either
explicitly change it or Emacs has no other choice.

If the value is @code{height}, then only the window's height is fixed;
if the value is @code{width}, then only the window's width is fixed.
Any other non-@code{nil} value fixes both the width and the height.

This variable automatically becomes buffer-local when set.
@end defvar

Commands supposed to explicitly change the size of windows such as
@code{enlarge-window} (@pxref{Resizing Windows}) get an error if they
had to change a window size which is fixed.  Other functions like
@code{window-resize} (@pxref{Resizing Windows}) have an optional
@var{ignore} argument which allows to change the size of fixed-size
windows.

   Deleting a window or changing a frame's size may change the size of a
fixed-size window, if there is no other alternative.

   The height of a vertical combination of windows cannot be changed
when the height of all these windows is fixed.  Its width cannot be
changed if the width of at least one of these windows is fixed.
Similarly, the width of a horizontal combination of windows cannot be
changed when the width of all these windows is fixed.  Its height cannot
be changed if the height of at least one of these windows is fixed.

   The next function allows to check whether the size of an arbitrary           
window is fixed.

@defun window-size-fixed-p &optional window horizontal
This function returns non-@code{nil} if @var{window}'s height is fixed.
The argument @var{window} can be an arbitrary window and defaults to the
selected one.  Optional argument @var{horizontal} non-@code{nil} means
return non-@code{nil} if @var{window}'s width is fixed.

If this function returns @code{nil}, this does not necessarily mean that
@var{window} can be resized in the desired direction.  The function
@code{window-resizable} (@pxref{Resizing Windows}) can tell that.
@end defun


@node Resizing Windows
@section Resizing Windows
@cindex window resizing
@cindex resize window
@cindex changing window size
@cindex window size, changing

Emacs does not permit overlapping windows or gaps between windows, so
changing the size of a window always affects at least one other window.
When a frame contains just one window, that window can be resized only
by resizing the window's frame.  The functions described below are
therefore meaningful only in the context of a frame containing at least
two windows.  The size of the corresponding frame never changes when
invoking a function described in this section.

   The routines changing window sizes always operate in one dimension at
a time.  This means that windows can be resized only either vertically
or horizontally.  If a window shall be resized in both dimensions, it
must be resized in one dimension first and in the other dimension
afterwards.  If the second resize operation fails, the frame might end
up in an unsatisfactory state.  To avoid such states, it might be useful
to save the current window configuration (@pxref{Window Configurations})
before attempting the first resize operation and restore the saved
configuration in case the second resize operation fails.

   Functions that resize windows are supposed to obey restrictions
imposed by window minimum sizes and fixed-size windows, see @ref{Window
Sizes}.  In order to determine whether resizing a specific window is
possible in the first place, the following function can be used:

@defun window-resizable window delta &optional horizontal ignore side noup nodown
This function returns @var{delta} if the size of @var{window} can be
changed vertically by @var{delta} lines.  Optional argument
@var{horizontal} non-@code{nil} means to return @var{delta} if
@var{window} can be resized horizontally by @var{delta} columns.  A
return value of zero means that @var{window} is not resizable.

If @var{delta} is a positive number, this means that @var{window} shall
be enlarged by @var{delta} lines or columns.  If @var{window} cannot be
enlarged by @var{delta} lines or columns, this function returns the
maximum value in the range from 0 to @var{delta} by which @var{window}
can be enlarged.

If @var{delta} is a negative number, this means that @var{window} shall
be shrunk by -@var{delta} lines or columns.  If @var{window} cannot be
shrunk by -@var{delta} lines or columns, this function returns the
minimum value in the range from @var{delta} to 0 that can be used for
shrinking @var{window}.

Optional argument @var{ignore} non-@code{nil} means ignore any
restrictions imposed by the variables @code{window-min-height} or
@code{window-min-width} and @code{window-size-fixed}.  In this case the
minimum height of a window is specified as the minimum number of lines
that allow viewing any header or mode line and at least one line of the
text area of window.  The minimum width of a window includes any
fringes, margins and the scroll bar as well as two text columns.

If @var{ignore} denotes a window, this means to ignore restrictions for
that window only.  If @var{ignore} equals the constant @code{safe}, this
means a live window may get as small as one line or two columns.

Optional argument @var{noup} non-@code{nil} means don't go up in the
window tree but try to steal or distribute the space needed for the
resize operation among the other windows within @var{window}'s
combination.  Optional argument @var{nodown} non-@code{nil} means don't
check whether @var{window} itself and its subwindows can be resized.
@end defun

The function @code{window-resizable} does not change any window sizes.
The following function does:

@defun window-resize window delta &optional horizontal ignore
This function resizes @var{window} vertically by @var{delta} lines.  The
argument @var{window} can denote an arbitrary window and defaults to the
selected one.  An attempt to resize the root window of a frame will
raise an error.

Second argument @var{delta} a positive number means @var{window} shall
be enlarged by @var{delta} lines.  If @var{delta} is negative, that
means @var{window} shall be shrunk by -@var{delta} lines.

Optional argument @var{horizontal} non-@code{nil} means to resize
@var{window} horizontally by @var{delta} columns.  In this case a
positive @var{delta} means enlarge @var{window} by @var{delta} columns.
A negative @var{delta} means @var{window} shall be shrunk by
-@var{delta} columns.

Optional argument @var{ignore} has the same meaning as for the function
@code{window-resizable} above.

This function can simultaneously move two edges of WINDOW.  Exactly
which edges of @var{window} are moved and which other windows are
resized along with @var{window} is determined by the splits and nest
status of the involved windows (@pxref{Splitting Windows}).  If only the
low (right) edge of @var{window} shall be moved, the function
@code{adjust-window-trailing-edge} described below should be used.
Glenn Morris's avatar
Glenn Morris committed
794 795
@end defun

796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932
The next four commands are simple interfaces to @code{window-resize}.
They always operate on the selected window, never delete any window, and
always raise an error when resizing would violate a restriction imposed
by @code{window-min-height}, @code{window-min-width}, or
@code{window-size-fixed}.

@deffn Command enlarge-window delta &optional horizontal
This function makes the selected window @var{delta} lines taller.
Interactively, if no argument is given, it makes the selected window one
line taller.  If optional argument @var{horizontal} is non-@code{nil},
it makes the selected window wider by @var{delta} columns.  If
@var{delta} is negative, it shrinks the selected window by -@var{delta}
lines or columns.  The return value is @code{nil}.
@end deffn

@deffn Command enlarge-window-horizontally delta
This function makes the selected window @var{delta} columns wider.
Interactively, if no argument is given, it makes the selected window one
column wider.
@end deffn

@deffn Command shrink-window delta &optional horizontal
This function makes the selected window @var{delta} lines smaller.
Interactively, if no argument is given, it makes the selected window one
line smaller.  If optional argument @var{horizontal} is non-@code{nil},
it makes the selected window narrower by @var{delta} columns.  If
@var{delta} is negative, it enlarges the selected window by -@var{delta}
lines or columns.  The return value is @code{nil}.
@end deffn

@deffn Command shrink-window-horizontally delta
This function makes the selected window @var{delta} columns narrower.
Interactively, if no argument is given, it makes the selected window one
column narrower.
@end deffn

The following function is useful for moving the line dividing two
windows.

@defun adjust-window-trailing-edge window delta &optional horizontal
This function moves @var{window}'s bottom edge by @var{delta} lines.
Optional argument @var{horizontal} non-@code{nil} means to move
@var{window}'s right edge by @var{delta} columns.  The argument
@var{window} defaults to the selected window.

If @var{delta} is greater zero, this moves the edge downwards or to the
right.  If @var{delta} is less than zero, this moves the edge upwards or
to the left. If the edge can't be moved by @var{delta} lines or columns,
it is moved as far as possible in the desired direction but no error is
signalled.

This function tries to resize windows adjacent to the edge that is
moved.  Only if this is insufficient, it will also resize windows not
adjacent to that edge.  As a consequence, if you move an edge in one
direction and back in the other direction by the same amount, the
resulting window configuration will not be necessarily identical to the
one before the first move.  So if your intend to just resize
@var{window}, you should not use this function but call
@code{window-resize} (see above) instead.
@end defun

@deffn Command fit-window-to-buffer &optional window max-height min-height override
This command makes @var{window} the right height to display its
contents exactly.  The default for @var{window} is the selected window.

The optional argument @var{max-height} specifies the maximum total
height the window is allowed to be; @code{nil} means use the maximum
permissible height of a window on @var{window}'s frame.  The optional
argument @var{min-height} specifies the minimum toatl height for the
window; @code{nil} means use @code{window-min-height}.  All these height
values include the mode line and/or header line.

If the optional argument @var{override} is non-@code{nil}, this means to
ignore any restrictions imposed by @code{window-min-height} and
@code{window-min-width} on the size of @var{window}.

This function returns non-@code{nil} if it orderly resized @var{window},
and @code{nil} otherwise.
@end deffn

@deffn Command shrink-window-if-larger-than-buffer &optional window
This command shrinks @var{window} vertically to be as small as possible
while still showing the full contents of its buffer---but not less than
@code{window-min-height} lines.  The argument @var{window} must denote
a live window and defaults to the selected one.

However, this command does nothing if the window is already too small to
display the whole text of the buffer, or if part of the contents are
currently scrolled off screen, or if the window is not the full width of
its frame, or if the window is the only window in its frame.

This command returns non-@code{nil} if it actually shrank the window
and @code{nil} otherwise.
@end deffn

@cindex balancing window sizes
Emacs provides two functions to balance windows, that is, to even out
the sizes of all windows on the same frame.  The minibuffer window and
fixed-size windows are not resized by these functions.

@deffn Command balance-windows &optional window-or-frame
This function balances windows in a way that gives more space to
full-width and/or full-height windows.  If @var{window-or-frame}
specifies a frame, it balances all windows on that frame.  If
@var{window-or-frame} specifies a window, it balances that window and
its siblings (@pxref{Windows and Frames}) only.
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
approximately the same share of the screen area.  This means that
full-width or full-height windows are not given more space than other
windows.
@end deffn

@cindex maximizing windows
The following function can be used to give a window the maximum possible
size without deleting other ones.

@deffn Command maximize-window &optional window
This function maximizes @var{window}.  More precisely, this makes
@var{window} as large as possible without resizing its frame or deleting
other windows.  @var{window} can be any window and defaults to the
selected one.
@end deffn

@cindex minimizing windows
To make a window as small as possible without deleting it the
following function can be used.

@deffn Command minimize-window &optional window
This function minimizes @var{window}.  More precisely, this makes
@var{window} as small as possible without deleting it or resizing its
frame.  @var{window} can be any window and defaults to the selected one.
@end deffn


Glenn Morris's avatar
Glenn Morris committed
933 934 935 936 937
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

938 939 940
The functions described below are the primitives needed for creating a
new window.  They do not accept a buffer as an argument.  Rather, they
``split'' an existing window into two halves, both displaying the buffer
Glenn Morris's avatar
Glenn Morris committed
941 942
previously visible in the window that was split.

943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995
@deffn Command split-window &optional window size side
This function creates a new window adjacent to @var{window}.  It returns
the new window which is always a live window.  The argument @var{window}
can denote any window and defaults to the selected one.  This function
does not change the selected window.

Optional second argument @var{size} a positive number means make
@var{window} @var{size} lines (or columns) tall.  If @var{size} is
negative, make the new window @minus{}@var{size} lines (or columns)
tall.  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.)

If splitting would result in making a window smaller than
@code{window-min-height} or @code{window-min-width} (@pxref{Window
Sizes}), this function usually signals an error.  However, if @var{size}
is non-@code{nil} and valid, a new window of the requested size is
created.  (A size value would be invalid if it assigned less than one
line or less than two columns to the new window.)

Optional third argument @var{side} @code{nil} (or @code{below})
specifies that the new window shall be located below @var{window}.  The
value @code{above} means the new window will be located above
@var{window}.  In both cases @var{size} specifies the new number of
lines for @var{window} (or the new window if @var{size} is negative)
including space reserved for the mode and/or header line.

If @var{side} is @code{t} or @code{right} the new window will be
positioned on the right side of @var{window}.  The value @code{left}
means the new window will be located on the left side of @var{window}.
In both cases @var{size} specifies the new number of columns for
@var{window} (or the new window provided @var{size} is negative)
including space reserved for margins, fringes and the scroll bar or a
divider column.

Any other non-@code{nil} value for @var{side} is currently handled like
@code{t} (or @code{right}).  Since this might change in the future,
application programs should refrain from using other values.

If @var{window} is live, properties of the new window like margins and
scroll bars are inherited from @var{window}.  If @var{window} is an
internal window, these properties, as well as the buffer shown in the
new window, are inherited from the window selected on @var{window}'s
frame.

If @code{ignore-window-parameters} is non-@code{nil}, this function
ignores window parameters (@pxref{Window Parameters}).  Otherwise, if
the @code{split-window} parameter of @var{window} is @code{t}, it splits
the window disregarding any other window parameters.  If the
@code{split-window} parameter specifies a function, that function is
called with the arguments @var{window}, @var{size}, and @var{side} to
split @var{window}.  If that function is @code{ignore}, nothing is done.
@end deffn
Glenn Morris's avatar
Glenn Morris committed
996 997 998 999 1000 1001

The following example starts with one window on a screen that is 50
lines high by 80 columns wide; then it splits the window.

@smallexample
@group
1002
(setq W1 (selected-window))
Glenn Morris's avatar
Glenn Morris committed
1003
     @result{} #<window 8 on windows.texi>
1004
(setq W2 (split-window W1 15))
Glenn Morris's avatar
Glenn Morris committed
1005 1006 1007
     @result{} #<window 28 on windows.texi>
@end group
@group
1008 1009 1010 1011 1012 1013
(window-top-line W1)
     @result{} 0
(window-total-size W1)
     @result{} 15
(window-top-line W2)
     @result{} 15
Glenn Morris's avatar
Glenn Morris committed
1014 1015 1016 1017 1018 1019 1020 1021 1022
@end group
@end smallexample

The screen looks like this:

@smallexample
@group
         __________
        |          |  line 0
1023
        |    W1    |
Glenn Morris's avatar
Glenn Morris committed
1024 1025
        |__________|
        |          |  line 15
1026
        |    W2    |
Glenn Morris's avatar
Glenn Morris committed
1027 1028 1029 1030 1031 1032
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

1033
Next, split the top window into two side-by-side windows:
Glenn Morris's avatar
Glenn Morris committed
1034 1035 1036

@smallexample
@group
1037
(setq W3 (split-window W1 35 t))
Glenn Morris's avatar
Glenn Morris committed
1038 1039 1040
     @result{} #<window 32 on windows.texi>
@end group
@group
1041 1042 1043 1044 1045 1046
(window-left-column W1)
     @result{} 0
(window-total-size W1 t)
     @result{} 35
(window-left-column W3)
     @result{} 35
Glenn Morris's avatar
Glenn Morris committed
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056
@end group
@end smallexample

@need 3000
Now the screen looks like this:

@smallexample
@group
     column 35
         __________
1057 1058 1059
        |    |     |  line 0
        | W1 |  W3 |
        |____|_____|
Glenn Morris's avatar
Glenn Morris committed
1060
        |          |  line 15
1061
        |    W2    |
Glenn Morris's avatar
Glenn Morris committed
1062 1063 1064 1065 1066 1067 1068
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

Normally, Emacs indicates the border between two side-by-side windows
1069 1070
with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters.  The
display table can specify alternative border characters; see @ref{Display
Martin Rudalics's avatar
Martin Rudalics committed
1071
Tables}.
Glenn Morris's avatar
Glenn Morris committed
1072

1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 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 1174 1175 1176 1177 1178 1179 1180 1181 1182 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 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557
Below we describe how @code{split-window} can be used to create the
window configuration from our earlier example (@pxref{Windows and
Frames}) and how internal windows are created for this purpose.  We
start with a frame containing one live window @code{W2} (in the
following scenarios window names are assigned in an arbitrary manner in
order to match the names of the example).  Evaluating the form
@code{(split-window W2 8 t)} creates a new internal window @code{W1}
with two children---@code{W2} (the window we've split) and a new leaf
window @code{W6}:
@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||      ||                            ||
    ||__W2__||_____________W6_____________ |
    |__________________W1__________________|

@end group
@end smallexample

Evaluating now @code{(split-window W6 -3)} creates another internal
window @code{W3} with two children---@code{W6} and a new live window
@code{W5}.  This leaves us with a vertically combined window @code{W3}
embedded in the horizontally combined window @code{W1}:
@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W6____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

Finally, evaluating @code{(split-window W6 nil t)} should get us the
desired configuration as depicted below.
@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      ||| ___________  ___________ |||
    ||      ||||           ||           ||||
    ||      ||||           ||           ||||
    ||      ||||_____W6____||_____W7____||||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

The scenario sketched above is the standard way to obtain the desired
configuration.  In Emacs 23 it was also the only way to do that since
Emacs 23 did't allow splitting internal windows.

With Emacs 24 you can also proceed as follows: Split an initial window
@code{W6} by evaluating @code{(split-window W6 -3)} to produce the
following vertical combination:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W6_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

Evaluating now @code{(split-window (window-parent W6) -8 'left)} or,
equivalently, @code{(split-window W3 -8 'left)} should now produce the
penultimate configuration from the previous scenario from where we can
continue as described before.

   Another strategy starts with splitting an inital window @code{W6} by
evaluating @code{(split-window W6 nil nil t)} with the following result:
@smallexample
@group
     ______________________________________
    | _________________  _________________ |
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||                 ||                 ||
    ||________W6_______||________W7_______||
    |__________________W4__________________|

@end group
@end smallexample

Evaluating now @code{(split-window W4 -3)} or @code{(split-window
(window-parent W6) -3)} should get us a configuration as shown next.
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    || ________________  ________________ ||
    |||                ||                |||
    |||                ||                |||
    |||                ||                |||
    |||                ||                |||
    |||                ||                |||
    |||_______W6_______||________W7______|||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

The desired configuration can be now obtained by evaluating
@code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window
(window-parent W5) -8 'left)}.

   For a final approach let's start with the configuration of two live
windows @code{W6} and @code{W7} shown above.  If we now evaluate
@code{(split-window W4 -8 'left)} or @code{(split-window (window-parent
W6) -8 'left)} we get the following configuration.
@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || ____________  ____________ ||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||            ||            |||
    ||      |||______W6____||______W7____|||
    ||__W2__||_____________W4_____________||
    |__________________W1__________________|

@end group
@end smallexample

Evaluating now @code{(split-window W4 -3)} or, for example,
@code{(split-window (window-parent W6) -3)} should produce the desired
configuration.

  The two options described next can be used to tune the operation of
@code{split-window}.

@defopt window-splits
If this variable is nil, the function @code{split-window} can split a
window if and only if that window's screen estate is sufficiently large
to accomodate both--itself and the new window.

If this variable is non-@code{nil}, @code{split-window} tries to resize
all windows that are part of the same combination as the old window to
accomodate the new window.  Hence, the new window can be also created if
the old window is of fixed size or too small to split (@pxref{Window
Sizes}).

In any case, the value of this variable is assigned to the splits status
of the new window and, provided old and new window form a new
combination, of the old window as well.  The splits status of a window
can be retrieved by invoking the function @code{window-splits} and
altered by the function @code{set-window-splits} described next.

If @code{window-nest} (see below) is non-@code{nil}, the space for the
new window is exclusively taken from the old window, but the splits
status of the involved windows is nevertheless set as described here.
@end defopt

@defun window-splits &optional window
This function returns the splits status of @var{window}.  The argument
@var{window} can be any window and defaults to the selected one.

@cindex splits status
The @dfn{splits status} of a window specifies how resizing and deleting
that window may affect the size of other windows in the same window
combination.  More precisely, if @var{window}'s splits status is
@code{nil} and @var{window} is resized, the corresponding space is
preferably taken from (or given to) @var{window}'s right sibling.  When
@var{window} is deleted, its space is given to its left sibling.  If
@var{window}'s splits status is non-@code{nil}, resizing and deleting
@var{window} may resize @emph{all} windows in @var{window}'s
combination.

The splits status is initially set by @code{split-window}
from the current value of the variable @code{window-splits} (see above)
and can be reset by the function @code{set-window-splits} (see below).
@end defun

@defun set-window-splits window &optional status
This function sets the splits status (see above) of @var{window} to
@var{status}.  The argument @var{window} can be any window and defaults
to the selected one.  The return value is @var{status}.
@end defun

To illustrate the use of @code{window-splits} consider the following
window configuration:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

Splitting window @code{W3} with @code{window-splits} @code{nil}
produces a configuration where the size of @code{W2} remains unchanged:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

Splitting @code{W3} with @code{window-splits} non-@code{nil} instead
produces a configuration where all windows have approximately the same
height:

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

@defopt window-nest
If this variable is @code{nil}, @code{split-window} creates a new parent
window if and only if the old window has no parent window or shall be
split orthogonally to the combination it is part of.  If this variable
is non-@code{nil}, @code{split-window} always creates a new parent
window.  If this variable is always non-@code{nil}, a frame's window
tree is a binary tree so every window but the frame's root window has
exactly one sibling.

The value of this variable is also assigned to the nest status of the
new parent window.  The nest status of any window can be retrieved via
the function @code{window-nest} and altered by the function
@code{set-window-nest}, see below.
@end defopt

@defun window-nest &optional window
This function returns the nest status of @var{window}.  The argument
@var{window} can be any window and defaults to the selected one.  Note,
however, that the nest status is currently meaningful for internal
windows only.

@cindex nest status
The @dfn{nest status} of a window specifies whether that window may be
removed and its subwindows recombined with that window's siblings when
such a sibling's subwindow is deleted.  The nest status is initially
assigned by @code{split-window} from the current value of the variable
@code{window-nest} (see above) and can be reset by the function
@code{set-window-nest} (see below).

If the return value is @code{nil}, subwindows of @var{window} may be
recombined with @var{window}'s siblings when a window gets deleted.  A
return value of @code{nil} means that subwindows of @var{window} are
never (re-)combined with @var{window}'s siblings in such a case.
@end defun

@defun set-window-nest window &optional status
This functions sets the nest status (see above) of @var{window} to
@var{status}.  The argument @var{window} can be any window and defaults
to the selected one.  Note that setting the nest status is meaningful
for internal windows only.  The return value is @var{status}.
@end defun

To illustrate the use of @code{window-nest} consider the following
configuration (throughout the following examples we shall assume that
@code{window-splits} invariantly is @code{nil}).
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

Splitting @code{W2} into two windows above each other with
@code{window-nest} equal @code{nil} will get you a configuration like:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

If you now enlarge window @code{W4}, Emacs steals the necessary space
from window @code{W3} resulting in a configuration like:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

Deleting window @code{W4}, will return its space to @code{W2} as
follows:
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

Hence, with respect to the initial configuration, window @code{W2} has
grown at the expense of window @code{W3}.  If, however, in the initial
configuration you had split @code{W2} with @code{window-nest} bound to
@code{t}, a new internal window @code{W5} would have been created as
depicted below.
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    || __________________________________ ||
    |||                                  |||
    |||________________W2________________|||
    || __________________________________ ||
    |||                                  |||
    |||________________W4________________|||
    ||_________________W5_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

Enlarging @code{W4} would now have stolen the necessary space from
@code{W2} instead of @code{W3} as
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    || __________________________________ ||
    |||________________W2________________|||
    || __________________________________ ||
    |||                                  |||
    |||                                  |||
    |||________________W4________________|||
    ||_________________W5_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

and the subsequent deletion of @code{W4} would have restored the initial
configuration.

For interactive use, Emacs provides two commands which always split the
selected window.

@deffn Command split-window-above-each-other &optional size
Glenn Morris's avatar
Glenn Morris committed
1558 1559 1560
This function splits the selected window into two windows, one above the
other, leaving the upper of the two windows selected, with @var{size}
lines.  (If @var{size} is negative, then the lower of the two windows
1561
gets @minus{}@var{size} lines and the upper window gets the rest, but
Glenn Morris's avatar
Glenn Morris committed
1562 1563 1564 1565
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.

1566 1567 1568
   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.
Glenn Morris's avatar
Glenn Morris committed
1569 1570 1571 1572
@end deffn

@defopt split-window-keep-point
If this variable is non-@code{nil} (the default), then
1573
@code{split-window-above-each-other} behaves as described above.
Glenn Morris's avatar
Glenn Morris committed
1574

1575 1576 1577 1578 1579
   If it is @code{nil}, then @code{split-window-above-each-other}
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.  Other functions are not
affected by this variable.
Glenn Morris's avatar
Glenn Morris committed
1580 1581
@end defopt

1582
@deffn Command split-window-side-by-side &optional size
Glenn Morris's avatar
Glenn Morris committed
1583 1584 1585
This function splits the selected window into two windows
side-by-side, leaving the selected window on the left with @var{size}
columns.  If @var{size} is negative, the rightmost window gets
1586
@minus{}@var{size} columns, but the leftmost window still remains
Glenn Morris's avatar
Glenn Morris committed
1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600
selected.
@end deffn


@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
1601 1602
deletes any windows that aren't part of that configuration.  Erroneous
information may result from using a deleted window as if it were live.
Glenn Morris's avatar
Glenn Morris committed
1603 1604

@deffn Command delete-window &optional window
Martin Rudalics's avatar
Martin Rudalics committed
1605
This function removes @var{window} from display and returns @code{nil}.
1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624
The argument @var{window} can denote any window and defaults to the
selected one.  An error is signaled if @var{window} is the only window
on its frame.  Hence @var{window} must have at least one sibling window
(@pxref{Windows and Frames}) in order to get deleted.

If the variable @code{ignore-window-parameters} (@pxref{Window
Parameters}) is non-@code{nil}, this function ignores all parameters of
@var{window}.  Otherwise, if the @code{delete-window} parameter of
@var{window} is @code{t}, it deletes the window disregarding other
window parameters.  If the @code{delete-window} parameter specifies a
function, that function is called with @var{window} as its sole
argument.

If the splits status of @var{window} (@pxref{Splitting Windows}) is
@code{nil}, the space @var{window} took up is given to its left sibling
if such a window exists and to its right sibling otherwise.  If the
splits status of @var{window} is non-@code{nil}, its space is
proportionally distributed among the remaining windows in the same
combination.
Glenn Morris's avatar
Glenn Morris committed
1625 1626 1627
@end deffn

@deffn Command delete-other-windows &optional window
1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638
This function makes @var{window} fill its frame and returns @code{nil}.
The argument @var{window} can denote an arbitrary window and defaults to
the selected one.

If the variable @code{ignore-window-parameters} (@pxref{Window
Parameters}) is non-@code{nil}, this function ignores all parameters of
@var{window}.  Otherwise, if the @code{delete-other-windows} parameter
of @var{window} equals @code{t}, it deletes all other windows
disregarding any remaining window parameters.  If the
@code{delete-other-windows} parameter of @var{window} specifies a
function, it calls that function with @var{window} as its sole argument.
Glenn Morris's avatar
Glenn Morris committed
1639 1640
@end deffn

1641
@deffn Command delete-windows-on &optional buffer-or-name frame
1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656
This function deletes all windows showing @var{buffer-or-name} and
returns nil.  If there are no windows showing @var{buffer-or-name}, it
does nothing.  The optional argument @var{buffer-or-name} may be a
buffer or the name of an existing buffer and defaults to the current
buffer.  Invoking this command on a minibuffer signals an error.

The function @code{delete-windows-on} operates by calling
@code{delete-window} for each window showing @var{buffer-or-name}.  If a
frame has several windows showing different buffers, then those showing
@var{buffer-or-name} are removed, and the other windows 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 that frame is deleted
provided there are other frames left.
Glenn Morris's avatar
Glenn Morris committed
1657

1658 1659
The optional argument @var{frame} specifies which frames to operate on.
This function does not use it in quite the same way as the other
1660 1661 1662
functions which scan all live windows (@pxref{Cyclic Window Ordering});
specifically, the values @code{t} and @code{nil} have the opposite of
their meanings in the other functions.  Here are the full details:
Glenn Morris's avatar
Glenn Morris committed
1663 1664

@itemize @bullet
1665 1666 1667 1668 1669 1670 1671 1672 1673 1674
@item @code{nil}
means operate on all frames.
@item @code{t}
means operate on the selected frame.
@item @code{visible}
means operate on all visible frames.
@item @code{0}
means operate on all visible or iconified frames.
@item A frame
means operate on that frame.
Glenn Morris's avatar
Glenn Morris committed
1675 1676 1677
@end itemize
@end deffn

1678

Glenn Morris's avatar
Glenn Morris committed
1679 1680 1681 1682 1683
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1684 1685 1686 1687 1688 1689
This function makes @var{window} the selected window, see @ref{Basic
Windows}.  Unless @var{window} already is the selected window, this also
makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
buffer.  Moreover, the cursor for selected windows will be displayed in
@var{window} after the next redisplay.  This function returns
@var{window}.
Glenn Morris's avatar
Glenn Morris committed
1690

Martin Rudalics's avatar
Martin Rudalics committed
1691 1692
Normally, @var{window}'s selected buffer is moved to the front of the
buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
1693 1694 1695
recently selected window.  But if the optional argument @var{norecord}
is non-@code{nil}, the buffer list remains unchanged and @var{window}
does not become the most recently selected one.
Glenn Morris's avatar
Glenn Morris committed
1696 1697
@end defun

1698 1699 1700 1701 1702 1703 1704
@cindex most recently selected windows
The sequence of calls to @code{select-window} with a non-@code{nil}
@var{norecord} argument determines an ordering of windows by their
selection time.  The function @code{get-lru-window} can be used to
retrieve the least recently selected live window in this ordering, see
@ref{Cyclic Window Ordering}.

Glenn Morris's avatar
Glenn Morris committed
1705 1706 1707 1708 1709 1710 1711
@defmac save-selected-window forms@dots{}
This macro records the selected frame, as well as the selected window
of each frame, executes @var{forms} in sequence, then restores the
earlier selected frame and windows.  It also saves and restores the
current buffer.  It returns the value of the last form in @var{forms}.

This macro does not save or restore anything about the sizes,
1712
arrangement or contents of windows; therefore, if @var{forms} change
Martin Rudalics's avatar
Martin Rudalics committed
1713 1714 1715 1716 1717 1718 1719 1720 1721
them, the change persists.  If the previously selected window 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.  The current buffer is restored if and
only if it is still live when exiting @var{forms}.

This macro changes neither the ordering of recently selected windows nor
the buffer list.
Glenn Morris's avatar
Glenn Morris committed
1722 1723 1724
@end defmac

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1725 1726 1727 1728
This macro selects @var{window}, executes @var{forms} in sequence, then
restores the previously selected window and current buffer.  The ordering
of recently selected windows and the buffer list remain unchanged unless
you deliberately change them within @var{forms}, for example, by calling
1729
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1730

1731 1732 1733
The order of recently selected windows and the buffer list are not
changed by this macro.
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1734

1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746
@cindex frame selected window
@cindex window selected within frame
Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
one window on any frame is selected within the frame.  The significance
of this designation is that selecting the frame also selects this
window.  Conversely, selecting a window for Emacs with
@code{select-window} also makes that window selected within its frame.

@defun frame-selected-window  &optional frame
This function returns the window on @var{frame} that is selected within
@var{frame}.  The optional argument @var{frame} must denote a live frame
and defaults to the selected one.
Glenn Morris's avatar
Glenn Morris committed
1747 1748
@end defun

1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759
@defun set-frame-selected-window frame window &optional norecord
This function sets the selected window of frame @var{frame} to
@var{window}.  The argument @var{frame} must denote a live frame and
defaults to the selected one.  If @var{frame} is the selected frame,
this also makes @var{window} the selected window.  The argument
@var{window} must denote a live window.  This function returns
@var{window}.

Optional argument @var{norecord} non-@code{nil} means to neither change
the list of most recently selected windows (@pxref{Selecting Windows})
nor the buffer list (@pxref{The Buffer List}).
Glenn Morris's avatar
Glenn Morris committed
1760 1761 1762 1763 1764 1765 1766 1767 1768
@end defun


@node Cyclic Window Ordering
@section Cyclic Ordering of Windows
@cindex cyclic ordering of windows
@cindex ordering of windows, cyclic
@cindex window ordering, cyclic

1769 1770 1771 1772
When you use the command @kbd{C-x o} (@code{other-window}) to select
some other window, it moves through live windows in a specific order.
For any given configuration of windows, this order never varies.  It is
called the @dfn{cyclic ordering of windows}.
Glenn Morris's avatar
Glenn Morris committed
1773

1774 1775 1776 1777
   For a particular frame, this ordering is determined by the window
tree of that frame, see @ref{Windows and Frames}.  More precisely, the
ordering is obtained by a depth-first traversal of the frame's window
tree supplemented, if requested, by the frame's minibuffer window.
Glenn Morris's avatar
Glenn Morris committed
1778

1779 1780 1781 1782 1783 1784
   If there's just one live frame, the cyclic ordering is the ordering
for that frame.  Otherwise, the cyclic ordering is obtained by appending
the orderings for individual frames in order of the list of all live
frames, @ref{Finding All Frames}.  In any case, the ordering is made
``cyclic'' by having the last window precede the first window in the
ordering.
Glenn Morris's avatar
Glenn Morris committed
1785

Juri Linkov's avatar
Juri Linkov committed
1786
@defun next-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1787 1788
@cindex minibuffer window, and @code{next-window}
This function returns the window following @var{window} in the cyclic
1789 1790
ordering of windows.  The argument @var{window} must specify a live
window and defaults to the selected one.
Glenn Morris's avatar
Glenn Morris committed
1791

1792 1793 1794 1795 1796 1797
The optional argument @var{minibuf} specifies whether minibuffer windows
shall be included in the cyclic ordering.  Normally, when @var{minibuf}
is @code{nil}, a minibuffer window is included only if it is currently
``active''; this matches the behavior of @kbd{C-x o}.  (Note that a
minibuffer window is active as long as its minibuffer is in use; see
@ref{Minibuffers}).
Glenn Morris's avatar
Glenn Morris committed
1798

1799 1800 1801
If @var{minibuf} is @code{t}, the cyclic ordering includes all
minibuffer windows.  If @var{minibuf} is neither @code{t} nor
@code{nil}, minibuffer windows are not included even if they are active.
Glenn Morris's avatar
Glenn Morris committed
1802

1803 1804
The optional argument @var{all-frames} specifies which frames to
consider.  Here are the possible values and their meanings:
Glenn Morris's avatar
Glenn Morris committed
1805

1806
@itemize @bullet
Glenn Morris's avatar
Glenn Morris committed
1807
@item @code{nil}
1808 1809
means consider all windows on @var{window}'s frame, plus the minibuffer
window used by that frame even if it lies in some other frame.  If the
Glenn Morris's avatar
Glenn Morris committed
1810 1811 1812 1813
minibuffer counts (as determined by @var{minibuf}), then all windows on
all frames that share that minibuffer count too.

@item @code{t}
1814
means consider all windows on all existing frames.
Glenn Morris's avatar
Glenn Morris committed
1815 1816

@item @code{visible}
1817 1818
means consider all windows on all visible frames.  (To get useful
results, ensure that @var{window} is on a visible frame.)
Glenn Morris's avatar
Glenn Morris committed
1819 1820

@item 0
1821
means consider all windows on all visible or iconified frames.
Glenn Morris's avatar
Glenn Morris committed
1822

1823 1824
@item A frame
means consider all windows on that frame.
Glenn Morris's avatar
Glenn Morris committed
1825

1826 1827 1828
@item Anything else
means consider the windows on @var{window}'s frame, and no others.
@end itemize
Glenn Morris's avatar
Glenn Morris committed
1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846

This example assumes there are two windows, both displaying the
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
Juri Linkov's avatar
Juri Linkov committed
1847
@end defun
Glenn Morris's avatar
Glenn Morris committed
1848

Juri Linkov's avatar
Juri Linkov committed
1849
@defun previous-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1850 1851
This function returns the window preceding @var{window} in the cyclic
ordering of windows.  The other arguments specify which windows to
1852
consider as in @code{next-window}.
Juri Linkov's avatar
Juri Linkov committed
1853
@end defun
Glenn Morris's avatar
Glenn Morris committed
1854 1855

@deffn Command other-window count &optional all-frames
Martin Rudalics's avatar
Martin Rudalics committed
1856 1857 1858 1859 1860 1861 1862 1863
This function selects another window in the cyclic ordering of windows.
@var{count} specifies the number of windows to skip in the ordering,
starting with the selected window, before making the selection.  If
@var{count} is a positive number, it skips @var{count} windows forwards.
@var{count} negative means skip @minus{}@var{count} windows backwards.
If @var{count} is zero, it does not skip any window, thus re-selecting
the selected window.  In an interactive call, @var{count} is the numeric
prefix argument.
Glenn Morris's avatar
Glenn Morris committed
1864

1865
The optional argument @var{all-frames} has the same meaning as in
Glenn Morris's avatar
Glenn Morris committed
1866
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
Martin Rudalics's avatar
Martin Rudalics committed
1867
is always effectively @code{nil}.  This function returns @code{nil}.
1868 1869 1870

This function does not select a window that has a non-@code{nil}
@code{no-other-window} window parameter (@pxref{Window Parameters}).
Glenn Morris's avatar
Glenn Morris committed
1871 1872
@end deffn

1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891
The following function returns a copy of the list of windows in the
cyclic odering.

@defun window-list-1 &optional window &optional minibuf &optional all_frames
This function returns a list of live windows.  The optional arguments
@var{minibuf} and @var{all-frames} specify the set of windows to include
in the list.  See the description of @code{next-window} for details.

The optional argument @var{window} specifies the first window to list
and defaults to the selected window.  If @var{window} is not on the list
of windows returned, some other window will be listed first but no error
is signalled.
@end defun

The functions described below use @code{window-list-1} for generating a
copy of the list of all relevant windows.  Hence, any change of the
window configuration that occurs while one of these functions is
executed is @emph{not} reflected in the list of windows investigated.

Glenn Morris's avatar
Glenn Morris committed
1892
@defun walk-windows proc &optional minibuf all-frames
1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944
This function cycles through live windows.  It calls the function
@var{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 walk, see @code{next-window} above.  If
@var{all-frames} specifies a frame, the first window walked is the first
window on that frame as returned by @code{frame-first-window} and not
necessarily the selected window.

If @var{proc} changes the window configuration by splitting or deleting
windows, that change is not reflected in the set of windows walked.
That set is determined entirely by the set of live windows at the time
this function was invoked.
@end defun

The following function allows to determine whether a specific window is