windows.texi 147 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
This function returns a non-@code{nil} value if and only if
@var{window} is part of a vertical combination.  If @var{window} is
277
omitted or @code{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
@end defun


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

545 546 547 548 549 550 551 552 553 554
  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.
555

Martin Rudalics's avatar
Martin Rudalics committed
556
@defun window-resizable window delta &optional horizontal ignore
557
This function returns @var{delta} if the size of @var{window} can be
558 559 560 561 562 563 564
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
565 566 567 568 569
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.
570 571 572 573 574 575 576 577 578 579 580

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.
581 582 583
@end defun

@defun window-resize window delta &optional horizontal ignore
584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600
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.

The choice of which window edge this function alters depends on the
splitting and nesting status of the involved windows; in some cases,
it may alter both edges.  @xref{Splitting Windows}.  To resize by
moving only the bottom or right edge of a window, use the function
@code{adjust-window-trailing-edge}, below.
Glenn Morris's avatar
Glenn Morris committed
601 602
@end defun

603 604 605
@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.
606

607
  The following function is useful for moving the line dividing two
608 609 610 611 612 613 614 615 616 617 618 619
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
620
signaled.
621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638

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
639
argument @var{min-height} specifies the minimum total height for the
640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707
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
708 709 710 711 712
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

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

716
@deffn Command split-window &optional window size side
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
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.

The optional second argument @var{size} determines the sizes of the
@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.

If the variable @code{ignore-window-parameters} is non-@code{nil}
(@pxref{Window Parameters}), this function ignores window parameters.
Otherwise, it consults the @code{split-window} parameter of
@var{window}; if this 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}, in
lieu of the usual action of @code{split-window}.
764
@end deffn
Glenn Morris's avatar
Glenn Morris committed
765

766 767 768 769 770 771
  As an example, we show a combination of @code{split-window} calls
that yields the window configuration discussed in @ref{Windows and
Frames}.  This example demonstrates splitting live windows as well as
splitting internal windows.  We begin with a frame containing a single
window (a live root window), which we denote by @var{W4}.  Calling
@code{(split-window W3)} yields this window configuration:
772 773 774 775 776 777 778 779

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
780 781
    ||_________________W4_________________||
    | ____________________________________ |
782 783 784 785 786 787 788 789 790
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

791 792 793 794 795
@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}.
796

797 798
  Next, we call @code{(split-window W3 nil 'left)}, passing the
internal window @var{W3} as the argument.  The result:
799 800 801 802 803

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
804 805 806 807 808 809 810 811 812 813
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
814 815 816 817
    |__________________W1__________________|
@end group
@end smallexample

818 819 820 821 822
@noindent
A new live window, @var{W2}, is created to the left of @var{W3} (which
encompasses the vertical window combination of @var{W4} and @var{W5}).
A new internal window @var{W1} is also created, and becomes the new
root window.
823

824
  The following two options can be used to modify the operation of
825 826 827
@code{split-window}.

@defopt window-splits
828 829 830 831 832 833 834 835 836 837
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.  This is
the default.

If this variable is non-@code{nil}, @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.
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 963 964 965 966

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
967 968 969 970
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
971 972
@code{set-window-nest} (see below).

973
If the return value is @code{nil}, child windows of @var{window} may be
974
recombined with @var{window}'s siblings when a window gets deleted.  A
975
return value of @code{nil} means that child windows of @var{window} are
976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 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 1025 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 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127
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.

1128
@deffn Command split-window-below &optional size
Glenn Morris's avatar
Glenn Morris committed
1129 1130 1131
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
1132
gets @minus{}@var{size} lines and the upper window gets the rest, but
Glenn Morris's avatar
Glenn Morris committed
1133 1134 1135 1136
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.

1137 1138 1139
   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
1140 1141 1142 1143
@end deffn

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

1146 1147 1148 1149 1150
   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
1151 1152
@end defopt

1153
@deffn Command split-window-right &optional size
Glenn Morris's avatar
Glenn Morris committed
1154 1155 1156
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
1157
@minus{}@var{size} columns, but the leftmost window still remains
Glenn Morris's avatar
Glenn Morris committed
1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171
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
1172 1173
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
1174 1175

@deffn Command delete-window &optional window
Martin Rudalics's avatar
Martin Rudalics committed
1176
This function removes @var{window} from display and returns @code{nil}.
1177 1178 1179
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
1180 1181 1182
(@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.
1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197

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
1198 1199 1200
@end deffn

@deffn Command delete-other-windows &optional window
1201 1202
This function makes @var{window} fill its frame and returns @code{nil}.
The argument @var{window} can denote an arbitrary window and defaults to
1203 1204
the selected one.  Upon exit, @var{window} will be the selected window
on its frame.
1205 1206 1207 1208 1209 1210 1211 1212

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
1213 1214
@end deffn

1215
@deffn Command delete-windows-on &optional buffer-or-name frame
1216 1217 1218 1219 1220
This function deletes all windows showing @var{buffer-or-name}.  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.
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230

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
1231

1232 1233
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
1234 1235 1236
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
1237 1238

@itemize @bullet
1239 1240 1241 1242 1243 1244 1245 1246 1247 1248
@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
1249 1250 1251
@end itemize
@end deffn

1252

Glenn Morris's avatar
Glenn Morris committed
1253 1254 1255 1256 1257
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1258 1259 1260 1261 1262 1263
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
1264

Martin Rudalics's avatar
Martin Rudalics committed
1265 1266
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
1267 1268 1269
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
1270 1271
@end defun

1272 1273 1274 1275 1276 1277 1278
@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
1279 1280 1281 1282 1283 1284 1285
@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,
1286
arrangement or contents of windows; therefore, if @var{forms} change
Martin Rudalics's avatar
Martin Rudalics committed
1287 1288 1289 1290 1291 1292 1293 1294 1295
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
1296 1297 1298
@end defmac

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1299 1300 1301 1302
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
1303
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1304

1305 1306 1307
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
1308

1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320
@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
1321 1322
@end defun

1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333
@defun set-frame-selected-window frame window &optional norecord
This function sets the selected window of frame @var{frame} to
@var{window}.  The argument @var{frame} must denote a live frame and
defaults to the selected one.  If @var{frame} is the selected frame,
this also makes @var{window} the selected window.  The argument
@var{window} must denote a live window.  This function returns
@var{window}.

Optional argument @var{norecord} non-@code{nil} means to neither change
the list of most recently selected windows (@pxref{Selecting Windows})
nor the buffer list (@pxref{The Buffer List}).
Glenn Morris's avatar
Glenn Morris committed
1334 1335 1336 1337 1338 1339 1340 1341 1342
@end defun


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

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

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

1353 1354 1355 1356 1357 1358
   If there's just one live frame, the cyclic ordering is the ordering
for that frame.  Otherwise, the cyclic ordering is obtained by appending
the orderings for individual frames in order of the list of all live
frames, @ref{Finding All Frames}.  In any case, the ordering is made
``cyclic'' by having the last window precede the first window in the
ordering.
Glenn Morris's avatar
Glenn Morris committed
1359

Juri Linkov's avatar
Juri Linkov committed
1360
@defun next-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1361 1362
@cindex minibuffer window, and @code{next-window}
This function returns the window following @var{window} in the cyclic
1363 1364
ordering of windows.  The argument @var{window} must specify a live
window and defaults to the selected one.
Glenn Morris's avatar
Glenn Morris committed
1365

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

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

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

1380
@itemize @bullet
Glenn Morris's avatar
Glenn Morris committed
1381
@item @code{nil}
1382 1383
means consider all windows on @var{window}'s frame, plus the minibuffer
window used by that frame even if it lies in some other frame.  If the
Glenn Morris's avatar
Glenn Morris committed
1384 1385 1386 1387
minibuffer counts (as determined by @var{minibuf}), then all windows on
all frames that share that minibuffer count too.

@item @code{t}
1388
means consider all windows on all existing frames.
Glenn Morris's avatar
Glenn Morris committed
1389 1390

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

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

1397 1398
@item A frame
means consider all windows on that frame.
Glenn Morris's avatar
Glenn Morris committed
1399

1400 1401 1402
@item Anything else
means consider the windows on @var{window}'s frame, and no others.
@end itemize
Glenn Morris's avatar
Glenn Morris committed
1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420

This example assumes there are two windows, both displaying the
buffer @samp{windows.texi}:

@example
@group
(selected-window)
     @result{} #<window 56 on windows.texi>
@end group
@group
(next-window (selected-window))
     @result{} #<window 52 on windows.texi>
@end group
@group
(next-window (next-window (selected-window)))
     @result{} #<window 56 on windows.texi>
@end group
@end example
Juri Linkov's avatar
Juri Linkov committed
1421
@end defun
Glenn Morris's avatar
Glenn Morris committed
1422

Juri Linkov's avatar
Juri Linkov committed
1423
@defun previous-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1424 1425
This function returns the window preceding @var{window} in the cyclic
ordering of windows.  The other arguments specify which windows to
1426
consider as in @code{next-window}.
Juri Linkov's avatar
Juri Linkov committed
1427
@end defun
Glenn Morris's avatar
Glenn Morris committed
1428 1429

@deffn Command other-window count &optional all-frames
Martin Rudalics's avatar
Martin Rudalics committed
1430 1431 1432 1433 1434 1435 1436 1437
This function selects another window in the cyclic ordering of windows.
@var{count} specifies the number of windows to skip in the ordering,
starting with the selected window, before making the selection.  If
@var{count} is a positive number, it skips @var{count} windows forwards.
@var{count} negative means skip @minus{}@var{count} windows backwards.
If @var{count} is zero, it does not skip any window, thus re-selecting
the selected window.  In an interactive call, @var{count} is the numeric
prefix argument.
Glenn Morris's avatar
Glenn Morris committed
1438

1439
The optional argument @var{all-frames} has the same meaning as in
Glenn Morris's avatar
Glenn Morris committed
1440
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
Martin Rudalics's avatar
Martin Rudalics committed
1441
is always effectively @code{nil}.  This function returns @code{nil}.
1442 1443 1444

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

1447
The following function returns a copy of the list of windows in the
1448
cyclic ordering.