windows.texi 154 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-2012
4
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Windows
Glenn Morris's avatar
Glenn Morris committed
7 8
@chapter Windows

9 10 11 12
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
13 14 15

@menu
* Basic Windows::           Basic information on using windows.
16 17 18
* 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.
19 20 21 22
* Splitting Windows::       Creating a new window.
* Deleting Windows::        Removing a window from its frame.
* Recombining Windows::     Preserving the frame layout when splitting and
                              deleting windows.
Glenn Morris's avatar
Glenn Morris committed
23 24 25
* 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.
26
* Switching Buffers::       Higher-level functions for switching to a buffer.
Glenn Morris's avatar
Glenn Morris committed
27
* Choosing Window::         How to choose a window for displaying a buffer.
28 29
* Display Action Functions:: Subroutines for @code{display-buffer}.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
30
* Window History::          Each window remembers the buffers displayed in it.
Glenn Morris's avatar
Glenn Morris committed
31
* Dedicated Windows::       How to avoid displaying another buffer in
32
                              a specific window.
33 34
* Quitting Windows::        How to restore the state prior to displaying a
                              buffer.
Glenn Morris's avatar
Glenn Morris committed
35
* Window Point::            Each window has its own location of point.
Martin Rudalics's avatar
Martin Rudalics committed
36 37
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
Glenn Morris's avatar
Glenn Morris committed
38 39 40 41 42
* 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
43
* Window Parameters::       Associating additional information with windows.
Glenn Morris's avatar
Glenn Morris committed
44 45 46 47 48
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
@end menu

49

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

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

@cindex multiple windows
59 60 61 62 63 64
  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
65

66 67
@cindex terminal screen
@cindex screen of terminal
68 69 70 71
  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).
72
When Emacs is run on a text terminal, the frame fills the entire
73
terminal screen.
Glenn Morris's avatar
Glenn Morris committed
74 75

@cindex tiled windows
76 77 78 79
  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.
80

81 82
@defun windowp object
This function returns @code{t} if @var{object} is a window (whether or
83
not it displays a buffer).  Otherwise, it returns @code{nil}.
84
@end defun
85

86 87 88 89
@cindex live windows
A @dfn{live window} is one that is actually displaying a buffer in a
frame.

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

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
@cindex internal windows
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 @dfn{internal windows}, which are not live.

@cindex valid windows
   A @dfn{valid window} is one that is either live or internal.  A valid
window can be @dfn{deleted}, i.e. removed from its frame
(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
object representing it might be still referenced from other Lisp
objects.  A deleted window may be made valid again by restoring a saved
window configuration (@pxref{Window Configurations}).

   You can distinguish valid windows from deleted windows with
110 111 112 113 114 115
@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.
116 117 118
@end defun

@cindex selected window
119
@cindex window selected within a frame
120 121 122 123 124 125 126 127 128
  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}.
129 130

@defun selected-window
131 132
This function returns the selected window (which is always a live
window).
133 134 135 136 137
@end defun

@node Windows and Frames
@section Windows and Frames

138
Each window belongs to exactly one frame (@pxref{Frames}).
139 140

@defun window-frame window
141 142 143
This function returns the frame that the window @var{window} belongs
to.  If @var{window} is @code{nil}, it defaults to the selected
window.
144 145
@end defun

146 147 148 149
@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.
150

151 152 153 154 155 156
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.
157

Martin Rudalics's avatar
Martin Rudalics committed
158 159 160 161
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 the first element.
162 163 164
@end defun

@cindex window tree
165 166 167 168 169 170 171 172 173 174 175 176 177 178
@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.
179 180

@defun frame-root-window &optional frame-or-window
181 182 183 184 185
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.
186 187
@end defun

188 189 190 191 192 193 194 195 196 197 198 199
@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}.
200 201 202

@cindex parent window
@defun window-parent &optional window
203 204 205 206
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).
207 208
@end defun

209 210 211 212 213 214 215 216 217 218
  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.
219 220 221 222

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
223 224 225 226 227 228
  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:
229 230 231 232 233 234

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
235 236 237
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
238 239 240
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
241
    ||      |||                          |||
242 243 244 245 246 247 248
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
@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}.
265 266
@end defun

267 268 269 270 271
@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}.
272 273 274
@end defun

@defun window-child window
275 276 277 278
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}.
279 280
@end defun

281
@defun window-combined-p &optional window horizontal
282 283
This function returns a non-@code{nil} value if and only if
@var{window} is part of a vertical combination.  If @var{window} is
284
omitted or @code{nil}, it defaults to the selected one.
285

286 287 288
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.
289 290 291
@end defun

@defun window-next-sibling &optional window
292 293 294 295
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.
296 297 298
@end defun

@defun window-prev-sibling &optional window
299 300 301 302
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.
303 304
@end defun

305 306
The functions @code{window-next-sibling} and
@code{window-prev-sibling} should not be confused with the functions
307 308
@code{next-window} and @code{previous-window}, which return the next
and previous window, respectively, in the cyclic ordering of windows
309
(@pxref{Cyclic Window Ordering}).
310

311 312
  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:
313 314 315 316 317 318 319 320 321 322 323 324

@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
325 326 327
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.
328 329

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

333 334 335 336 337 338 339 340 341 342
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}).
343 344 345 346 347 348 349
@end defun

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

350
  The following schematic shows the structure of a live window:
351 352 353

@smallexample
@group
354 355
         _________________________________________
      ^ |______________ Header Line_______________|
356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
      | |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
371
@cindex text area of a window
372
@cindex body of a window
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
385
a window.  Except where noted, Emacs reports window heights and widths
386
as integer numbers of lines and columns, respectively.  On a graphical
387 388 389 390 391
display, each ``line'' and ``column'' actually corresponds to the
height and width of a ``default'' character specified by the frame's
default font.  Thus, if a window is displaying text with a different
font or size, the reported height and width for that window may differ
from the actual number of text lines or columns displayed within it.
392 393 394 395 396 397 398

@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
399 400 401 402 403 404 405
  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}).
406 407

@defun window-total-height &optional window
408 409 410 411
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.
412 413 414
@end defun

@defun window-total-width &optional window
415 416 417 418 419
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
420

421 422 423 424 425 426
@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}.
427 428 429
@end defun

@cindex full-width window
430 431 432 433 434 435 436 437 438 439
@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
440 441

@defun window-full-width-p &optional window
442 443 444 445
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.
446 447 448 449 450 451 452 453
@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
454 455 456 457
  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.
458 459

@defun window-body-height &optional window
460 461 462
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.
463

464 465 466
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.
467 468 469
@end defun

@defun window-body-width &optional window
470 471 472
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.
473 474
@end defun

475 476 477 478 479
@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}.
480 481
@end defun

482 483 484
@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.
485 486
@end defun

487
  For compatibility with previous versions of Emacs,
488
@code{window-height} is an alias for @code{window-total-height}, and
489 490
@code{window-width} is an alias for @code{window-body-width}.  These
aliases are considered obsolete and will be removed in the future.
491 492

@cindex fixed-size window
493 494 495 496 497 498 499 500
  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:

501
@defvar window-size-fixed
502 503 504 505
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.
506 507 508 509 510 511 512

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
513 514 515 516 517
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.
518

519 520 521
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}.
522 523
@end defun

524 525 526 527 528 529
  @xref{Coordinates and Windows}, for more functions that report the
positions of various parts of a window relative to the frame, from
which you can calculate its size.  In particular, you can use the
functions @code{window-pixel-edges} and
@code{window-inside-pixel-edges} to find the size in pixels, for
graphical displays.
530 531 532 533 534 535 536 537

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

538 539 540 541 542 543 544 545 546 547
  This section describes functions for resizing a window without
changing the size of its frame.  Because live windows do not overlap,
these functions are meaningful only on frames that contain two or more
windows: resizing a window also changes the size of a neighboring
window.  If there is just one window on a frame, its size cannot be
changed except by resizing the frame (@pxref{Size and Position}).

  Except where noted, these functions also accept internal windows as
arguments.  Resizing an internal window causes its child windows to be
resized to fit the same space.
548

Martin Rudalics's avatar
Martin Rudalics committed
549
@defun window-resizable window delta &optional horizontal ignore
550
This function returns @var{delta} if the size of @var{window} can be
551 552 553 554 555 556 557
changed vertically by @var{delta} lines.  If the optional argument
@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
@var{window} can be resized horizontally by @var{delta} columns.  It
does not actually change the window size.

If @var{window} is @code{nil}, it defaults to the selected window.

Martin Rudalics's avatar
Martin Rudalics committed
558 559 560 561 562
A positive value of @var{delta} means to check whether the window can be
enlarged by that number of lines or columns; a negative value of
@var{delta} means to check whether the window can be shrunk by that many
lines or columns.  If @var{delta} is non-zero, a return value of 0 means
that the window cannot be resized.
563 564 565 566 567 568 569 570 571 572 573

Normally, the variables @code{window-min-height} and
@code{window-min-width} specify the smallest allowable window size.
@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
Emacs Manual}.  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}.
Instead, it considers the minimum-height window to be one consisting
of a header (if any), a mode line, plus a text area one line tall; and
a minimum-width window as one consisting of fringes, margins, and
scroll bar (if any), plus a text area two columns wide.
574 575 576
@end defun

@defun window-resize window delta &optional horizontal ignore
577 578 579 580 581 582 583 584 585 586 587 588
This function resizes @var{window} by @var{delta} increments.  If
@var{horizontal} is @code{nil}, it changes the height by @var{delta}
lines; otherwise, it changes the width by @var{delta} columns.  A
positive @var{delta} means to enlarge the window, and a negative
@var{delta} means to shrink it.

If @var{window} is @code{nil}, it defaults to the selected window.  If
the window cannot be resized as demanded, an error is signaled.

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

589
The choice of which window edges this function alters depends on the
590
values of the option @code{window-combination-resize} and the
591
combination limits of the involved windows; in some cases, it may alter
592
both edges.  @xref{Recombining Windows}.  To resize by moving only the
593
bottom or right edge of a window, use the function
594
@code{adjust-window-trailing-edge}, below.
Glenn Morris's avatar
Glenn Morris committed
595 596
@end defun

597 598 599
@c The commands enlarge-window, enlarge-window-horizontally,
@c shrink-window, and shrink-window-horizontally are documented in the
@c Emacs manual.  They are not preferred for calling from Lisp.
600 601 602

@defun adjust-window-trailing-edge window delta &optional horizontal
This function moves @var{window}'s bottom edge by @var{delta} lines.
603 604 605
If optional argument @var{horizontal} is non-@code{nil}, it instead
moves the right edge by @var{delta} columns.  If @var{window} is
@code{nil}, it defaults to the selected window.
606

607 608 609 610
A positive @var{delta} moves the edge downwards or to the right; a
negative @var{delta} moves it upwards or to the left.  If the edge
cannot be moved as far as specified by @var{delta}, this function
moves it as far as possible but does not signal a error.
611 612

This function tries to resize windows adjacent to the edge that is
613 614
moved.  If this is not possible for some reason (e.g. if that adjacent
window is fixed-size), it may resize other windows.
615 616
@end defun

617 618 619
  The following commands resize windows in more specific ways.  When
called interactively, they act on the selected window.

620
@deffn Command fit-window-to-buffer &optional window max-height min-height override
621 622 623 624 625 626 627 628
This command adjusts the height of @var{window} to fit the text in it.
It returns non-@code{nil} if it was able to resize @var{window}, and
@code{nil} otherwise.  If @var{window} is omitted or @code{nil}, it
defaults to the selected window.  Otherwise, it should be a live
window.

The optional argument @var{max-height}, if non-@code{nil}, specifies
the maximum total height that this function can give @var{window}.
629
The optional argument @var{min-height}, if non-@code{nil}, specifies
630 631 632 633 634 635
the minimum total height that it can give, which overrides the
variable @code{window-min-height}.

If the optional argument @var{override} is non-@code{nil}, this
function ignores any size restrictions imposed by
@code{window-min-height} and @code{window-min-width}.
636 637 638
@end deffn

@deffn Command shrink-window-if-larger-than-buffer &optional window
639 640 641 642 643 644 645 646 647 648
This command attempts to reduce @var{window}'s height as much as
possible while still showing its full buffer, but no less than
@code{window-min-height} lines.  The return value is non-@code{nil} if
the window was resized, and @code{nil} otherwise.  If @var{window} is
omitted or @code{nil}, it defaults to the selected window.  Otherwise,
it should be a live window.

This command does nothing if the window is already too short to
display all of its buffer, or if any of the buffer is scrolled
off-screen, or if the window is the only live window in its frame.
649 650 651 652 653 654 655
@end deffn

@cindex balancing window sizes
@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
656 657
@var{window-or-frame} specifies a window, it balances only that window
and its siblings (@pxref{Windows and Frames}).
658 659 660 661
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
662 663
approximately the same share of the screen area.  Full-width or
full-height windows are not given more space than other windows.
664 665 666 667
@end deffn

@cindex maximizing windows
@deffn Command maximize-window &optional window
668 669 670 671
This function attempts to make @var{window} as large as possible, in
both dimensions, without resizing its frame or deleting other windows.
If @var{window} is omitted or @code{nil}, it defaults to the selected
window.
672 673 674 675
@end deffn

@cindex minimizing windows
@deffn Command minimize-window &optional window
676 677 678 679
This function attempts to make @var{window} as small as possible, in
both dimensions, without deleting it or resizing its frame.  If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
680 681 682
@end deffn


Glenn Morris's avatar
Glenn Morris committed
683 684 685 686 687
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

688 689
This section describes functions for creating a new window by
@dfn{splitting} an existing one.
Glenn Morris's avatar
Glenn Morris committed
690

691
@deffn Command split-window &optional window size side
692 693 694 695 696
This function creates a new live window next to the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
to the selected window.  That window is ``split'', and reduced in
size.  The space is taken up by the new window, which is returned.

697
The optional second argument @var{size} determines the sizes of
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
@var{window} and/or the new window.  If it is omitted or @code{nil},
both windows are given equal sizes; if there is an odd line, it is
allocated to the new window.  If @var{size} is a positive number,
@var{window} is given @var{size} lines (or columns, depending on the
value of @var{side}).  If @var{size} is a negative number, the new
window is given @minus{}@var{size} lines (or columns).

If @var{size} is @code{nil}, this function obeys the variables
@code{window-min-height} and @code{window-min-width}.  @xref{Change
Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
Manual}.  Thus, it signals an error if splitting would result in
making a window smaller than those variables specify.  However, a
non-@code{nil} value for @var{size} causes those variables to be
ignored; in that case, the smallest allowable window is considered to
be one that has space for a text area one line tall and/or two columns
wide.

The optional third argument @var{side} determines the position of the
new window relative to @var{window}.  If it is @code{nil} or
@code{below}, the new window is placed below @var{window}.  If it is
@code{above}, the new window is placed above @var{window}.  In both
these cases, @var{size} specifies a total window height, in lines.

If @var{side} is @code{t} or @code{right}, the new window is placed on
the right of @var{window}.  If @var{side} is @code{left}, the new
window is placed on the left of @var{window}.  In both these cases,
@var{size} specifies a total window width, in columns.

If @var{window} is a live window, the new window inherits various
properties from it, including margins and scroll bars.  If
@var{window} is an internal window, the new window inherits the
properties of the window selected within @var{window}'s frame.

731 732
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
733
@code{ignore-window-parameters} is @code{nil}.  If the value of
734 735 736 737 738 739 740
the @code{split-window} window parameter is @code{t}, this function
ignores all other window parameters.  Otherwise, if the value of the
@code{split-window} window parameter is a function, that function is
called with the arguments @var{window}, @var{size}, and @var{side}, in
lieu of the usual action of @code{split-window}.  Otherwise, this
function obeys the @code{window-atom} or @code{window-side} window
parameter, if any.  @xref{Window Parameters}.
741
@end deffn
Glenn Morris's avatar
Glenn Morris committed
742

743 744 745 746 747
  As an example, here is a sequence of @code{split-window} calls that
yields the window configuration discussed in @ref{Windows and Frames}.
This example demonstrates splitting a live window as well as splitting
an internal window.  We begin with a frame containing a single window
(a live root window), which we denote by @var{W4}.  Calling
Martin Rudalics's avatar
Martin Rudalics committed
748
@code{(split-window W4)} yields this window configuration:
749 750 751 752 753 754 755 756

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
757 758
    ||_________________W4_________________||
    | ____________________________________ |
759 760 761 762 763 764 765 766 767
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

768 769 770 771 772
@noindent
The @code{split-window} call has created a new live window, denoted by
@var{W5}.  It has also created a new internal window, denoted by
@var{W3}, which becomes the root window and the parent of both
@var{W4} and @var{W5}.
773

774 775
  Next, we call @code{(split-window W3 nil 'left)}, passing the
internal window @var{W3} as the argument.  The result:
776 777 778 779 780

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
781 782 783 784 785 786 787 788 789 790
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
791 792 793 794
    |__________________W1__________________|
@end group
@end smallexample

795
@noindent
796 797 798
A new live window @var{W2} is created, to the left of the internal
window @var{W3}.  A new internal window @var{W1} is created, becoming
the new root window.
799

800 801
   For interactive use, Emacs provides two commands which always split
the selected window.  These call @code{split-window} internally.
802

803 804 805 806 807 808
@deffn Command split-window-right &optional size
This function splits the selected window into two side-by-side
windows, putting the selected window on the left.  If @var{size} is
positive, the left window gets @var{size} columns; if @var{size} is
negative, the right window gets @minus{}@var{size} columns.
@end deffn
809

810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826
@deffn Command split-window-below &optional size
This function splits the selected window into two windows, one above
the other, leaving the upper window selected.  If @var{size} is
positive, the upper window gets @var{size} lines; if @var{size} is
negative, the lower window gets @minus{}@var{size} lines.
@end deffn

@defopt split-window-keep-point
If the value of this variable is non-@code{nil} (the default),
@code{split-window-below} behaves as described above.

If it is @code{nil}, @code{split-window-below} adjusts point in each
of the two windows to minimize redisplay.  (This is useful on slow
terminals.)  It selects whichever window contains the screen line that
point was previously on.  Note that this only affects
@code{split-window-below}, not the lower-level @code{split-window}
function.
Martin Rudalics's avatar
Martin Rudalics committed
827
@end defopt
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 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
@node Deleting Windows
@section Deleting Windows
@cindex deleting windows

  @dfn{Deleting} a window removes it from the frame's window tree.  If
the window is a live window, it disappears from the screen.  If the
window is an internal window, its child windows are deleted too.

  Even after a window is deleted, it continues to exist as a Lisp
object, until there are no more references to it.  Window deletion can
be reversed, by restoring a saved window configuration (@pxref{Window
Configurations}).

@deffn Command delete-window &optional window
This function removes @var{window} from display and returns
@code{nil}.  If @var{window} is omitted or @code{nil}, it defaults to
the selected window.  If deleting the window would leave no more
windows in the window tree (e.g. if it is the only live window in the
frame), an error is signaled.

By default, the space taken up by @var{window} is given to one of its
adjacent sibling windows, if any.  However, if the variable
@code{window-combination-resize} is non-@code{nil}, the space is
proportionally distributed among any remaining windows in the window
combination.  @xref{Recombining Windows}.

The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}.  If the value of
the @code{delete-window} window parameter is @code{t}, this function
ignores all other window parameters.  Otherwise, if the value of the
@code{delete-window} window parameter is a function, that function is
called with the argument @var{window}, in lieu of the usual action of
@code{delete-window}.  Otherwise, this function obeys the
@code{window-atom} or @code{window-side} window parameter, if any.
@xref{Window Parameters}.
@end deffn

@deffn Command delete-other-windows &optional window
This function makes @var{window} fill its frame, by deleting other
windows as necessary.  If @var{window} is omitted or @code{nil}, it
defaults to the selected window.  The return value is @code{nil}.

The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}.  If the value of
the @code{delete-other-windows} window parameter is @code{t}, this
function ignores all other window parameters.  Otherwise, if the value
of the @code{delete-other-windows} window parameter is a function,
that function is called with the argument @var{window}, in lieu of the
usual action of @code{delete-other-windows}.  Otherwise, this function
obeys the @code{window-atom} or @code{window-side} window parameter,
if any.  @xref{Window Parameters}.
@end deffn

@deffn Command delete-windows-on &optional buffer-or-name frame
This function deletes all windows showing @var{buffer-or-name}, by
calling @code{delete-window} on those windows.  @var{buffer-or-name}
should be a buffer, or the name of a buffer; if omitted or @code{nil},
it defaults to the current buffer.  If there are no windows showing
the specified buffer, this function does nothing.  If the specified
buffer is a minibuffer, an error is signaled.

If there is a dedicated window showing the buffer, and that window is
the only one on its frame, this function also deletes that frame if it
is not the only frame on the terminal.

The optional argument @var{frame} specifies which frames to operate
on:

@itemize @bullet
@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.
@end itemize

Note that this argument does not have the same meaning as in other
functions which scan all live windows (@pxref{Cyclic Window
Ordering}).  Specifically, the meanings of @code{t} and @code{nil} here
are the opposite of what they are in those other functions.
@end deffn


@node Recombining Windows
@section Recombining Windows

When deleting the last sibling of a window @code{W}, its parent window
is deleted too, with @code{W} replacing it in the window tree.  This
means that @code{W} must be recombined with its parent's siblings to
form a new window combination (@pxref{Windows and Frames}).  In some
occasions, deleting a live window may even entail the deletion of two
internal windows.

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

@end group
@end smallexample

@noindent
Deleting @code{W5} in this configuration normally causes the deletion of
@code{W3} and @code{W4}.  The remaining live windows @code{W2},
@code{W6} and @code{W7} are recombined to form a new horizontal
combination with parent @code{W1}.

   Sometimes, however, it makes sense to not delete a parent window like
@code{W4}.  In particular, a parent window should not be removed when it
was used to preserve a combination embedded in a combination of the same
type.  Such embeddings make sense to assure that when you split a window
and subsequently delete the new window, Emacs reestablishes the layout
of the associated frame as it existed before the splitting.

   Consider a scenario starting with two live windows @code{W2} and
@code{W3} and their parent @code{W1}.
963

964 965 966 967 968 969 970 971 972 973
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
974 975
    ||_________________W2_________________||
    | ____________________________________ |
976 977 978 979 980 981 982 983
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

984
@noindent
985
Split @code{W2} to make a new window @code{W4} as follows.
986

987 988 989 990 991 992 993 994 995 996 997
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
998 999 1000 1001
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
1002 1003 1004 1005 1006
    |__________________W1__________________|

@end group
@end smallexample

1007
@noindent
1008 1009 1010 1011
Now, when enlarging a window vertically, Emacs tries to obtain the
corresponding space from its lower sibling, provided such a window
exists.  In our scenario, enlarging @code{W4} will steal space from
@code{W3}.
1012

1013 1014 1015 1016 1017 1018 1019 1020 1021 1022
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
1023 1024 1025 1026
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
1027
    ||_________________W3_________________||
1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039
    |__________________W1__________________|

@end group
@end smallexample

@noindent
Deleting @code{W4} will now give its entire space to @code{W2},
including the space earlier stolen from @code{W3}.

@smallexample
@group
     ______________________________________
1040 1041 1042
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
1043 1044 1045 1046 1047 1048 1049 1050 1051
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||_________________W3_________________||
1052 1053 1054 1055 1056
    |__________________W1__________________|

@end group
@end smallexample

1057 1058 1059 1060 1061 1062 1063 1064
@noindent
This can be counterintutive, in particular if @code{W4} were used for
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
you want to continue working with the initial layout.

The behavior can be fixed by making a new parent window when splitting
@code{W2}.  The variable described next allows to do that.

1065
@defopt window-combination-limit
1066 1067 1068 1069 1070 1071
This variable controls whether splitting a window shall make a new
parent window.  The following values are recognized:

@table @code
@item nil
This means that the new live window is allowed to share the existing
1072
parent window, if one exists, provided the split occurs in the same
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
direction as the existing window combination (otherwise, a new internal
window is created anyway).

@item window-size
In this case @code{display-buffer} makes a new parent window if it is
passed a @code{window-height} or @code{window-width} entry in the
@var{alist} argument (@pxref{Display Action Functions}).

@item temp-buffer
This value causes the creation of a new parent window when a window is
split for showing a temporary buffer (@pxref{Temporary Displays}) only.

@item display-buffer
This means that when @code{display-buffer} (@pxref{Choosing Window})
splits a window it always makes a new parent window.

@item t
In this case a new parent window is always created when splitting a
window.  Thus, if the value of this variable is at all times @code{t},
then at all times every window tree is a binary tree (a tree where each
window except the root window has exactly one sibling).
@end table

The default is @code{nil}.  Other values are reserved for future use.

If, as a consequence of this variable's setting, @code{split-window}
makes a new parent window, it also calls
@code{set-window-combination-limit} (see below) on the newly-created
internal window.  This affects how the window tree is rearranged when
the child windows are deleted (see below).
1103 1104
@end defopt

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
  If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
the initial configuration of our scenario would have produced this:

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    || __________________________________ ||
    |||                                  |||
    |||________________W2________________|||
    || __________________________________ ||
    |||                                  |||
    |||________________W4________________|||
    ||_________________W5_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

@noindent
A new internal window @code{W5} has been created; its children are
@code{W2} and the new live window @code{W4}.  Now, @code{W2} is the only
sibling of @code{W4}, so enlarging @code{W4} will try to shrink
@code{W2}, leaving @code{W3} unaffected.  Observe that @code{W5}
represents a vertical combination of two windows embedded in the
vertical combination @code{W1}.

1136
@cindex window combination limit
1137
@defun set-window-combination-limit window limit
1138
This functions sets the @dfn{combination limit} of the window
1139
@var{window} to @var{limit}.  This value can be retrieved via the
1140 1141
function @code{window-combination-limit}.  See below for its effects;
note that it is only meaningful for internal windows.  The
1142
@code{split-window} function automatically calls this function, passing
1143 1144
it @code{t} as @var{limit}, provided the value of the variable
@code{window-combination-limit} is @code{t} when it is called.
1145 1146
@end defun

1147 1148 1149
@defun window-combination-limit window
This function returns the combination limit for @var{window}.

1150 1151
The combination limit is meaningful only for an internal window.  If it
is @code{nil}, then Emacs is allowed to automatically delete
1152
@var{window}, in response to a window deletion, in order to group the
1153 1154
child windows of @var{window} with its sibling windows to form a new
window combination.  If the combination limit is @code{t}, the child
1155
windows of @var{window} are never automatically recombined with its
1156
siblings.
1157 1158 1159 1160 1161

If, in the configuration shown at the beginning of this section, the
combination limit of @code{W4} (the parent window of @code{W6} and
@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
@code{W4} too.
1162 1163
@end defun

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
Alternatively, the problems sketched above can be avoided by always
resizing all windows in the same combination whenever one of its windows
is split or deleted.  This also permits to split windows that would be
otherwise too small for such an operation.

@defopt window-combination-resize
If this variable is @code{nil}, @code{split-window} can only split a
window (denoted by @var{window}) if @var{window}'s screen area is large
enough to accommodate both itself and the new window.

If this variable is @code{t}, @code{split-window} tries to resize all
windows that are part of the same combination as @var{window}, in order
to accommodate the new window.  In particular, this may allow
@code{split-window} to succeed even if @var{window} is a fixed-size
window or too small to ordinarily split.  Furthermore, subsequently
resizing or deleting @var{window} may resize all other windows in its
combination.

The default is @code{nil}.  Other values are reserved for future use.
The value of this variable is ignored when
@code{window-combination-limit} is non-@code{nil}.
@end defopt

  To illustrate the effect of @code{window-combination-resize}, consider
the following frame layout.
1189

1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
1202 1203
    ||                                    ||
    ||                                    ||
1204 1205 1206 1207 1208 1209
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

1210
@noindent
1211 1212
If @code{window-combination-resize} is @code{nil}, splitting window
@code{W3} leaves the size of @code{W2} unchanged:
1213 1214 1215 1216 1217 1218 1219 1220 1221

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
1222
    ||_________________W2_________________||
1223 1224 1225
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
1226 1227 1228
    | ____________________________________ |
    ||                                    ||
    ||_________________W4_________________||
1229 1230 1231 1232 1233
    |__________________W1__________________|

@end group
@end smallexample

1234
@noindent
1235 1236 1237
If @code{window-combination-resize} is @code{t}, splitting @code{W3}
instead leaves all three live windows with approximately the same
height:
1238 1239 1240 1241 1242

@smallexample
@group
     ______________________________________
    | ____________________________________ |
1243 1244 1245
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
1246 1247 1248 1249
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
1250 1251 1252 1253
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
1254 1255 1256 1257 1258
    |__________________W1__________________|

@end group
@end smallexample

1259
@noindent
1260 1261 1262
Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
distribute its space proportionally among the two remaining live
windows.
Glenn Morris's avatar
Glenn Morris committed
1263

1264

Glenn Morris's avatar
Glenn Morris committed
1265 1266 1267 1268 1269
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1270
This function makes @var{window} the selected window, as well as the
1271 1272 1273 1274 1275 1276 1277 1278 1279
window selected within its frame (@pxref{Basic Windows}).  @var{window}
must be a live window.  This function makes also @var{window}'s buffer
current (@pxref{Buffers and Windows}).  The return value is
@var{window}.

By default, this function also moves @var{window}'s buffer to the front
of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
most recently selected window.  However, if the optional argument
@var{norecord} is non-@code{nil}, these additional actions are omitted.
Glenn Morris's avatar
Glenn Morris committed
1280 1281
@end defun

1282
@cindex most recently selected windows
1283
  The sequence of calls to @code{select-window} with a non-@code{nil}
1284 1285
@var{norecord} argument determines an ordering of windows by their
selection time.  The function @code{get-lru-window} can be used to
1286 1287
retrieve the least recently selected live window (@pxref{Cyclic Window
Ordering}).
1288

Glenn Morris's avatar
Glenn Morris committed
1289 1290 1291 1292 1293 1294 1295
@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,
1296
arrangement or contents of windows; therefore, if @var{forms} change
Martin Rudalics's avatar
Martin Rudalics committed
1297 1298 1299 1300 1301 1302 1303 1304 1305
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
1306 1307 1308
@end defmac

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1309 1310 1311
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
1312
you deliberately change them within @var{forms}; for example, by calling
1313
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1314

1315 1316
This macro does not change the order of recently selected windows or
the buffer list.
1317
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1318

1319 1320 1321 1322
@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected
within that frame.  @var{frame} should be a live frame; if omitted or
@code{nil}, it defaults to the selected frame.
Glenn Morris's avatar
Glenn Morris committed
1323 1324
@end defun

1325
@defun set-frame-selected-window frame window &optional norecord
1326
This function makes @var{window} the window selected within the frame
1327 1328 1329 1330
@var{frame}.  @var{frame} should be a live frame; if omitted or
@code{nil}, it defaults to the selected frame.  @var{window} should be
a live window; if omitted or @code{nil}, it defaults to the selected
window.