windows.texi 157 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.
32 33
* Quitting Windows::        How to restore the state prior to displaying a
                              buffer.
Glenn Morris's avatar
Glenn Morris committed
34
* Window Point::            Each window has its own location of point.
Martin Rudalics's avatar
Martin Rudalics committed
35 36
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
Glenn Morris's avatar
Glenn Morris committed
37 38 39 40 41
* 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
42
* Window Parameters::       Associating additional information with windows.
Glenn Morris's avatar
Glenn Morris committed
43 44 45 46 47
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
@end menu

48

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

53 54 55
A @dfn{window} is a area of the screen which is used to display a
buffer (@pxref{Buffers}).  In Emacs Lisp, windows are represented by a
special Lisp object type.
Glenn Morris's avatar
Glenn Morris committed
56 57

@cindex multiple windows
58 59 60 61 62 63
  Windows are grouped into frames (@pxref{Frames}).  Each frame
contains at least one window; the user can subdivide it into multiple,
non-overlapping windows to view several buffers at once.  Lisp
programs can use multiple windows for a variety of purposes.  In
Rmail, for example, you can view a summary of message titles in one
window, and the contents of the selected message in another window.
Glenn Morris's avatar
Glenn Morris committed
64

65 66
@cindex terminal screen
@cindex screen of terminal
67 68 69 70 71 72
  Emacs uses the word ``window'' with a different meaning than in
graphical desktop environments and window systems, such as the X
Window System.  When Emacs is run on X, each of its graphical X
windows is an Emacs frame (containing one or more Emacs windows).
When Emacs is run on a text-only terminal, the frame fills the entire
terminal screen.
Glenn Morris's avatar
Glenn Morris committed
73 74

@cindex tiled windows
75 76 77 78
  Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
within the area of the frame.  When a window is created, resized, or
deleted, the change in window space is taken from or given to the
adjacent windows, so that the total area of the frame is unchanged.
79 80 81

@cindex live windows
@cindex internal windows
82 83 84 85 86 87 88 89 90 91 92
  A @dfn{live window} is one that is actually displaying a buffer in a
frame.  Such a window can be @dfn{deleted}, i.e. removed from the
frame (@pxref{Deleting Windows}); then it is no longer live, but the
Lisp object representing it might be still referenced from other Lisp
objects.  A deleted window may be brought back to life by restoring a
saved window configuration (@pxref{Window Configurations}).

@defun windowp object
This function returns @code{t} if @var{object} is a window (whether or
not it is live).  Otherwise, it returns @code{nil}.
@end defun
93 94 95

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

99 100 101 102 103 104 105 106 107 108 109
  The windows in each frame are organized into a @dfn{window tree}.
@xref{Windows and Frames}.  The leaf nodes of each window tree are
live windows---the ones actually displaying buffers.  The internal
nodes of the window tree are internal windows, which are not live.
You can distinguish internal windows from deleted windows with
@code{window-valid-p}.

@defun window-valid-p object
This function returns @code{t} if @var{object} is a live window, or an
internal window in a window tree.  Otherwise, it returns @code{nil},
including for the case where @var{object} is a deleted window.
110 111 112
@end defun

@cindex selected window
113 114 115 116 117 118 119 120 121
  In each frame, at any time, exactly one Emacs window is designated
as @dfn{selected within the frame}.  For the selected frame, that
window is called the @dfn{selected window}---the one in which most
editing takes place, and in which the cursor for selected windows
appears (@pxref{Cursor Parameters}).  The selected window's buffer is
usually also the current buffer, except when @code{set-buffer} has
been used (@pxref{Current Buffer}).  As for non-selected frames, the
window selected within the frame becomes the selected window if the
frame is ever selected.  @xref{Selecting Windows}.
122 123

@defun selected-window
124 125
This function returns the selected window (which is always a live
window).
126 127 128 129 130
@end defun

@node Windows and Frames
@section Windows and Frames

131
Each window belongs to exactly one frame (@pxref{Frames}).
132 133

@defun window-frame window
134 135 136
This function returns the frame that the window @var{window} belongs
to.  If @var{window} is @code{nil}, it defaults to the selected
window.
137 138
@end defun

139 140 141 142
@defun window-list &optional frame minibuffer window
This function returns a list of live windows belonging to the frame
@var{frame}.  If @var{frame} is omitted or @code{nil}, it defaults to
the selected frame.
143

144 145 146 147 148 149
The optional argument @var{minibuffer} specifies whether to include
the minibuffer window in the returned list.  If @var{minibuffer} is
@code{t}, the minibuffer window is included.  If @var{minibuffer} is
@code{nil} or omitted, the minibuffer window is included only if it is
active.  If @var{minibuffer} is neither @code{nil} nor @code{t}, the
minibuffer window is never included.
150

151 152 153 154
The optional argument @var{window}, if non-@code{nil}, should be a
live window on the specified frame; then @var{window} will be the
first element in the returned list.  If @var{window} is omitted or
@code{nil}, the window selected within the frame is first element.
155 156 157
@end defun

@cindex window tree
158 159 160 161 162 163 164 165 166 167 168 169 170 171
@cindex root window
  Windows in the same frame are organized into a @dfn{window tree},
whose leaf nodes are the live windows.  The internal nodes of a window
tree are not live; they exist for the purpose of organizing the
relationships between live windows.  The root node of a window tree is
called the @dfn{root window}.  It can be either a live window (if the
frame has just one window), or an internal window.

  A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
frame's window tree unless the frame is a minibuffer-only frame.
Nonetheless, most of the functions in this section accept the
minibuffer window as an argument.  Also, the function
@code{window-tree} described at the end of this section lists the
minibuffer window alongside the actual window tree.
172 173

@defun frame-root-window &optional frame-or-window
174 175 176 177 178
This function returns the root window for @var{frame-or-window}.  The
argument @var{frame-or-window} should be either a window or a frame;
if omitted or @code{nil}, it defaults to the selected frame.  If
@var{frame-or-window} is a window, the return value is the root window
of that window's frame.
179 180
@end defun

181 182 183 184 185 186 187 188 189 190 191 192
@cindex parent window
@cindex child window
@cindex sibling window
  When a window is split, there are two live windows where previously
there was one.  One of these is represented by the same Lisp window
object as the original window, and the other is represented by a
newly-created Lisp window object.  Both of these live windows become
leaf nodes of the window tree, as @dfn{child windows} of a single
internal window.  If necessary, Emacs automatically creates this
internal window, which is also called the @dfn{parent window}, and
assigns it to the appropriate position in the window tree.  A set of
windows that share the same parent are called @dfn{siblings}.
193 194 195

@cindex parent window
@defun window-parent &optional window
196 197 198 199
This function returns the parent window of @var{window}.  If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.  The return value is @code{nil} if @var{window} has no parent
(i.e. it is a minibuffer window or the root window of its frame).
200 201
@end defun

202 203 204 205 206 207 208 209 210 211
  Each internal window always has at least two child windows.  If this
number falls to one as a result of window deletion, Emacs
automatically deletes the internal window, and its sole remaining
child window takes its place in the window tree.

  Each child window can be either a live window, or an internal window
(which in turn would have its own child windows).  Therefore, each
internal window can be thought of as occupying a certain rectangular
@dfn{screen area}---the union of the areas occupied by the live
windows that are ultimately descended from it.
212 213 214 215

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
216 217 218 219 220 221
  For each internal window, the screen areas of the immediate children
are arranged either vertically or horizontally (never both).  If the
child windows are arranged one above the other, they are said to form
a @dfn{vertical combination}; if they are arranged side by side, they
are said to form a @dfn{horizontal combination}.  Consider the
following example:
222 223 224 225 226 227

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
228 229 230
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
231 232 233
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
234
    ||      |||                          |||
235 236 237 238 239 240 241
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
@noindent
The root window of this frame is an internal window, @code{W1}.  Its
child windows form a horizontal combination, consisting of the live
window @code{W2} and the internal window @code{W3}.  The child windows
of @code{W3} form a vertical combination, consisting of the live
windows @code{W4} and @code{W5}.  Hence, the live windows in this
window tree are @code{W2} @code{W4}, and @code{W5}.

  The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.

@defun window-top-child window
This function returns the topmost child window of @var{window}, if
@var{window} is an internal window whose children form a vertical
combination.  For any other type of window, the return value is
@code{nil}.
258 259
@end defun

260 261 262 263 264
@defun window-left-child window
This function returns the leftmost child window of @var{window}, if
@var{window} is an internal window whose children form a horizontal
combination.  For any other type of window, the return value is
@code{nil}.
265 266 267
@end defun

@defun window-child window
268 269 270 271
This function returns the first child window of the internal window
@var{window}---the topmost child window for a vertical combination, or
the leftmost child window for a horizontal combination.  If
@var{window} is a live window, the return value is @code{nil}.
272 273
@end defun

274
@defun window-combined-p &optional window horizontal
275 276 277
This function returns a non-@code{nil} value if and only if
@var{window} is part of a vertical combination.  If @var{window} is
omitted or nil, it defaults to the selected one.
278

279 280 281
If the optional argument @var{horizontal} is non-@code{nil}, this
means to return non-@code{nil} if and only if @var{window} is part of
a horizontal combination.
282 283 284
@end defun

@defun window-next-sibling &optional window
285 286 287 288
This function returns the next sibling of the window @var{window}.  If
omitted or @code{nil}, @var{window} defaults to the selected window.
The return value is @code{nil} if @var{window} is the last child of
its parent.
289 290 291
@end defun

@defun window-prev-sibling &optional window
292 293 294 295
This function returns the previous sibling of the window @var{window}.
If omitted or @code{nil}, @var{window} defaults to the selected
window.  The return value is @code{nil} if @var{window} is the first
child of its parent.
296 297
@end defun

298 299 300 301 302
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
(@pxref{Cyclic Window Ordering}).
303

304 305
  You can use the following functions to find the first live window on
a frame, and to retrieve the entire window tree of a frame:
306 307 308 309 310 311 312 313 314 315 316 317

@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

@defun window-tree &optional frame
318 319 320
This function returns a list representing the window tree for frame
@var{frame}.  If @var{frame} is omitted or @code{nil}, it defaults to
the selected frame.
321 322

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

326 327 328 329 330 331 332 333 334 335
If the root window is live, @var{root} is that window itself.
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 window object
(for a live window) or a list with the same format as above (for an
internal window).  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} (@pxref{Coordinates and Windows}).
336 337 338 339 340 341 342
@end defun

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

343
  The following schematic shows the structure of a live window:
344 345 346

@smallexample
@group
347 348
         _________________________________________
      ^ |______________ Header Line_______________|
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
      | |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
364
@cindex text area of a window
365
@cindex body of a window
366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
  At the center of the window is the @dfn{text area}, or @dfn{body},
where the buffer text is displayed.  On each side of the text area is
a series of vertical areas; from innermost to outermost, these are the
left and right margins, denoted by LM and RM in the schematic
(@pxref{Display Margins}); the left and right fringes, denoted by LF
and RF (@pxref{Fringes}); and the left or right scroll bar, only one of
which is present at any time, denoted by LS and RS (@pxref{Scroll
Bars}).  At the top of the window is an optional header line
(@pxref{Header Lines}), and at the bottom of the window is the mode
line (@pxref{Mode Line Format}).

  Emacs provides several functions for finding the height and width of
a window.  Most of these functions report the values as integer
multiples of the default character height and width.  On a graphical
display, the actual screen size of this default height and width are
those specified by the frame's default font.  Hence, if the buffer
contains text that is displayed in a different size, the reported
height and width of the window may differ from the actual number of
text lines or columns displayed in it.
385 386 387 388 389 390 391

@cindex window height
@cindex height of a window
@cindex total height of a window
@cindex window width
@cindex width of a window
@cindex total width of a window
392 393 394 395 396 397 398
  The @dfn{total height} of a window is the distance between the top
and bottom of the window, including the header line (if one exists)
and the mode line.  The @dfn{total width} of a window is the distance
between the left and right edges of the mode line.  Note that the
height of a frame is not the same as the height of its windows, since
a frame may also contain an echo area, menu bar, and tool bar
(@pxref{Size and Position}).
399 400

@defun window-total-height &optional window
401 402 403 404
This function returns the total height, in lines, of the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window.  If @var{window} is an internal window, the
return value is the total height occupied by its descendant windows.
405 406 407
@end defun

@defun window-total-width &optional window
408 409 410 411 412
This function returns the total width, in columns, of the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window.  If @var{window} is internal, the return value
is the total width occupied by its descendant windows.
@end defun
413

414 415 416 417 418 419
@defun window-total-size &optional window horizontal
This function returns either the total height or width of the window
@var{window}.  If @var{horizontal} is omitted or @code{nil}, this is
equivalent to calling @code{window-total-height} for @var{window};
otherwise it is equivalent to calling @code{window-total-width} for
@var{window}.
420 421 422
@end defun

@cindex full-width window
423 424 425 426 427 428 429 430 431 432
@cindex full-height window
  The following functions can be used to determine whether a given
window has any adjacent windows.

@defun window-full-height-p &optional window
This function returns non-@code{nil} if @var{window} has no other
window above or below it in its frame, i.e. its total height equals
the total height of the root window on that frame.  If @var{window} is
omitted or @code{nil}, it defaults to the selected window.
@end defun
433 434

@defun window-full-width-p &optional window
435 436 437 438
This function returns non-@code{nil} if @var{window} has no other
window to the left or right in its frame, i.e. its total width equals
that of the root window on that frame.  If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
439 440
@end defun

441 442 443
@cindex window position
  The following functions can be used to determine the position of a
window relative to the window area of its frame:
444 445

@defun window-top-line &optional window
446 447 448 449 450
This function returns the distance, in lines, between the top of
@var{window} and the top of the frame's window area.  For instance,
the return value is 0 if there is no window above @var{window}.  If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
451 452 453
@end defun

@defun window-left-column &optional window
454 455 456 457 458
This function returns the distance, in columns, between the left edge
of @var{window} and the left edge of the frame's window area.  For
instance, the return value is 0 if there is no window to the left of
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window.
459 460 461 462 463 464 465 466
@end defun

@cindex window body height
@cindex body height of a window
@cindex window body width
@cindex body width of a window
@cindex body size of a window
@cindex window body size
467 468 469 470
  The @dfn{body height} of a window is the height of its text area,
which does not include the mode or header line.  Similarly, the
@dfn{body width} is the width of the text area, which does not include
the scroll bar, fringes, or margins.
471 472

@defun window-body-height &optional window
473 474 475
This function returns the body height, in lines, of the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window; otherwise it must be a live window.
476

477 478 479
If there is a partially-visible line at the bottom of the text area,
that counts as a whole line; to exclude such a partially-visible line,
use @code{window-text-height}, below.
480 481 482
@end defun

@defun window-body-width &optional window
483 484 485
This function returns the body width, in columns, of the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window; otherwise it must be a live window.
486 487
@end defun

488 489 490 491 492
@defun window-body-size &optional window horizontal
This function returns the body height or body width of @var{window}.
If @var{horizontal} is omitted or @code{nil}, it is equivalent to
calling @code{window-body-height} for @var{window}; otherwise it is
equivalent to calling @code{window-body-width}.
493 494
@end defun

495 496 497
@defun window-text-height &optional window
This function is like @code{window-body-height}, except that any
partially-visible line at the bottom of the text area is not counted.
498 499
@end defun

500 501 502 503
  For compatibility with previous versions of Emacs,
@code{window-height} is an alias for @code{window-body-height}, and
@code{window-width} is an alias for @code{window-body-width}.  These
aliases are considered obsolete and will be removed in the future.
504 505

@cindex fixed-size window
506 507 508 509 510 511 512 513
  Commands that change the size of windows (@pxref{Resizing Windows}),
or split them (@pxref{Splitting Windows}), obey the variables
@code{window-min-height} and @code{window-min-width}, which specify
the smallest allowable window height and width.  @xref{Change
Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
Manual}.  They also obey the variable @code{window-size-fixed}, with
which a window can be @dfn{fixed} in size:

514
@defvar window-size-fixed
515 516 517 518
If this buffer-local variable is non-@code{nil}, the size of any
window displaying the buffer cannot normally be changed.  Deleting a
window or changing the frame's size may still change its size, if
there is no choice.
519 520 521 522 523 524 525

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.
@end defvar

@defun window-size-fixed-p &optional window horizontal
526 527 528 529 530
This function returns a non-@code{nil} value if @var{window}'s height
is fixed.  If @var{window} is omitted or @code{nil}, it defaults to
the selected window.  If the optional argument @var{horizontal} is
non-@code{nil}, the return value is non-@code{nil} if @var{window}'s
width is fixed.
531

532 533 534
A @code{nil} return value does not necessarily mean that @var{window}
can be resized in the desired direction.  To determine that, use the
function @code{window-resizable}.  @xref{Resizing Windows}.
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
@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}.

587 588 589 590 591 592 593 594 595 596 597
Normally, the customizable variables @code{window-min-height} and
@code{window-min-width} specify the smallest allowable size of a
window.  @xref{Change Window,,Deleting and Rearranging Windows,
emacs, The GNU Emacs Manual}.  If resizing would result in making any
window smaller than this, this function usually signals an error.
However, if the optional argument @var{ignore} is non-@code{nil}, this
function ignores @code{window-min-height} and @code{window-min-width},
as well as @code{window-size-fixed}.  In that case, the minimum-height
window consists of a header (if any), a mode line, plus a text area
one line tall; the minimum-width window consists of any fringes,
margins and scroll bar, plus a text area two columns wide.
598 599 600 601 602 603 604 605 606

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
607
check whether @var{window} itself and its child windows can be resized.
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
@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
638 639
@end defun

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
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
689
signaled.
690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707

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
708
argument @var{min-height} specifies the minimum total height for the
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
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
777 778 779 780 781
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

782 783 784
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
785 786
previously visible in the window that was split.

787 788 789 790 791 792 793 794 795 796 797 798 799
@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.)

800 801 802 803 804 805 806 807
Normally, the customizable variables @code{window-min-height} and
@code{window-min-width} specify the smallest allowable size of a
window.  @xref{Change Window,,Deleting and Rearranging Windows, emacs,
The GNU Emacs Manual}.  If splitting would result in making a window
smaller than this, 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, provided it has enough space for a text
area one line tall and/or two columns wide.
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

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
842 843 844 845 846 847

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
848
(setq W1 (selected-window))
Glenn Morris's avatar
Glenn Morris committed
849
     @result{} #<window 8 on windows.texi>
850
(setq W2 (split-window W1 15))
Glenn Morris's avatar
Glenn Morris committed
851 852 853
     @result{} #<window 28 on windows.texi>
@end group
@group
854 855 856 857 858 859
(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
860 861 862 863 864 865 866 867 868
@end group
@end smallexample

The screen looks like this:

@smallexample
@group
         __________
        |          |  line 0
869
        |    W1    |
Glenn Morris's avatar
Glenn Morris committed
870 871
        |__________|
        |          |  line 15
872
        |    W2    |
Glenn Morris's avatar
Glenn Morris committed
873 874 875 876 877 878
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

879
Next, split the top window into two side-by-side windows:
Glenn Morris's avatar
Glenn Morris committed
880 881 882

@smallexample
@group
883
(setq W3 (split-window W1 35 t))
Glenn Morris's avatar
Glenn Morris committed
884 885 886
     @result{} #<window 32 on windows.texi>
@end group
@group
887 888 889 890 891 892
(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
893 894 895 896 897 898 899 900 901 902
@end group
@end smallexample

@need 3000
Now the screen looks like this:

@smallexample
@group
     column 35
         __________
903 904 905
        |    |     |  line 0
        | W1 |  W3 |
        |____|_____|
Glenn Morris's avatar
Glenn Morris committed
906
        |          |  line 15
907
        |    W2    |
Glenn Morris's avatar
Glenn Morris committed
908 909 910 911 912 913 914
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

Normally, Emacs indicates the border between two side-by-side windows
915 916
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
917
Tables}.
Glenn Morris's avatar
Glenn Morris committed
918

919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 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
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
995
Emacs 23 didn't allow splitting internal windows.
996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024

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.

Juanma Barranquero's avatar
Juanma Barranquero committed
1025
   Another strategy starts with splitting an initial window @code{W6} by
1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 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
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
Juanma Barranquero's avatar
Juanma Barranquero committed
1106
to accommodate both--itself and the new window.
1107 1108 1109

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
Juanma Barranquero's avatar
Juanma Barranquero committed
1110
accommodate the new window.  Hence, the new window can be also created if
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
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
1242 1243 1244 1245
removed and its child windows recombined with that window's siblings
when such a sibling's child window 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
1246 1247
@code{set-window-nest} (see below).

1248
If the return value is @code{nil}, child windows of @var{window} may be
1249
recombined with @var{window}'s siblings when a window gets deleted.  A
1250
return value of @code{nil} means that child windows of @var{window} are
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
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.

1403
@deffn Command split-window-below &optional size
Glenn Morris's avatar
Glenn Morris committed
1404 1405 1406
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
1407
gets @minus{}@var{size} lines and the upper window gets the rest, but
Glenn Morris's avatar
Glenn Morris committed
1408 1409 1410 1411
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.

1412 1413 1414
   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
1415 1416 1417 1418
@end deffn

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

1421 1422 1423 1424 1425
   If it is @code{nil}, then @code{split-window-below} 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
1426 1427
@end defopt

1428
@deffn Command split-window-right &optional size
Glenn Morris's avatar
Glenn Morris committed
1429 1430 1431
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
1432
@minus{}@var{size} columns, but the leftmost window still remains
Glenn Morris's avatar
Glenn Morris committed
1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446
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
1447 1448
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
1449 1450

@deffn Command delete-window &optional window
Martin Rudalics's avatar
Martin Rudalics committed
1451
This function removes @var{window} from display and returns @code{nil}.
1452 1453 1454
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
1455 1456 1457
(@pxref{Windows and Frames}) in order to get deleted.  If @var{window}
is the selected window on its frame, this function selects the most
recently selected live window on that frame instead.
1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472

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
1473 1474 1475
@end deffn

@deffn Command delete-other-windows &optional window
1476 1477
This function makes @var{window} fill its frame and returns @code{nil}.
The argument @var{window} can denote an arbitrary window and defaults to
1478 1479
the selected one.  Upon exit, @var{window} will be the selected window
on its frame.
1480 1481 1482 1483 1484 1485 1486 1487

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
1488 1489
@end deffn

1490
@deffn Command delete-windows-on &optional buffer-or-name frame
1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505
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
1506

1507 1508
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
1509 1510 1511
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
1512 1513

@itemize @bullet
1514 1515 1516 1517 1518 1519 1520 1521 1522 1523
@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
1524 1525 1526
@end itemize
@end deffn

1527

Glenn Morris's avatar
Glenn Morris committed
1528 1529 1530 1531 1532
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1533 1534 1535 1536 1537 1538
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
1539

Martin Rudalics's avatar
Martin Rudalics committed
1540 1541
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
1542 1543 1544
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
1545 1546
@end defun

1547 1548 1549 1550 1551 1552 1553
@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
1554 1555 1556 1557 1558 1559 1560
@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,
1561
arrangement or contents of windows; therefore, if @var{forms} change
Martin Rudalics's avatar
Martin Rudalics committed
1562 1563 1564 1565 1566 1567 1568 1569 1570
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
1571 1572 1573
@end defmac

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1574 1575 1576 1577
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
1578
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1579

1580 1581 1582
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
1583

1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595
@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
1596 1597
@end defun

1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608
@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}).