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

47

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

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

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

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

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

@cindex live windows
@cindex internal windows
81 82 83 84 85 86 87 88 89 90 91
  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
92 93 94

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

98 99 100 101 102 103 104 105 106 107 108
  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.
109 110 111
@end defun

@cindex selected window
112
@cindex window selected within a frame
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

Martin Rudalics's avatar
Martin Rudalics committed
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 the 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
The functions @code{window-next-sibling} and
@code{window-prev-sibling} should not be confused with the functions
300 301
@code{next-window} and @code{previous-window}, which return the next
and previous window, respectively, in the cyclic ordering of windows
302
(@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
  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
378
a window.  Except where noted, Emacs reports window heights and widths
379
as integer numbers of lines and columns, respectively.  On a graphical
380 381 382 383 384
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.
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 441 442 443 444 445 446
@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
447 448 449 450
  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.
451 452

@defun window-body-height &optional window
453 454 455
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.
456

457 458 459
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.
460 461 462
@end defun

@defun window-body-width &optional window
463 464 465
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.
466 467
@end defun

468 469 470 471 472
@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}.
473 474
@end defun

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

480
  For compatibility with previous versions of Emacs,
481
@code{window-height} is an alias for @code{window-total-height}, and
482 483
@code{window-width} is an alias for @code{window-body-width}.  These
aliases are considered obsolete and will be removed in the future.
484 485

@cindex fixed-size window
486 487 488 489 490 491 492 493
  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:

494
@defvar window-size-fixed
495 496 497 498
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.
499 500 501 502 503 504 505

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
506 507 508 509 510
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.
511

512 513 514
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}.
515 516
@end defun

517 518 519 520 521 522
  @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.
523 524 525 526 527 528 529 530

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

531 532 533 534 535 536 537 538 539 540
  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.
541

Martin Rudalics's avatar
Martin Rudalics committed
542
@defun window-resizable window delta &optional horizontal ignore
543
This function returns @var{delta} if the size of @var{window} can be
544 545 546 547 548 549 550
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
551 552 553 554 555
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.
556 557 558 559 560 561 562 563 564 565 566

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.
567 568 569
@end defun

@defun window-resize window delta &optional horizontal ignore
570 571 572 573 574 575 576 577 578 579 580 581
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.

582
The choice of which window edges this function alters depends on the
583
values of the option @code{window-combination-resize} and the
584 585 586
combination limits 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
587
@code{adjust-window-trailing-edge}, below.
Glenn Morris's avatar
Glenn Morris committed
588 589
@end defun

590 591 592
@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.
593 594 595

@defun adjust-window-trailing-edge window delta &optional horizontal
This function moves @var{window}'s bottom edge by @var{delta} lines.
596 597 598
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.
599

600 601 602 603
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.
604 605

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

610 611 612
  The following commands resize windows in more specific ways.  When
called interactively, they act on the selected window.

613
@deffn Command fit-window-to-buffer &optional window max-height min-height override
614 615 616 617 618 619 620 621
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}.
622
The optional argument @var{min-height}, if non-@code{nil}, specifies
623 624 625 626 627 628
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}.
629 630 631
@end deffn

@deffn Command shrink-window-if-larger-than-buffer &optional window
632 633 634 635 636 637 638 639 640 641
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.
642 643 644 645 646 647 648
@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
649 650
@var{window-or-frame} specifies a window, it balances only that window
and its siblings (@pxref{Windows and Frames}).
651 652 653 654
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
655 656
approximately the same share of the screen area.  Full-width or
full-height windows are not given more space than other windows.
657 658 659 660
@end deffn

@cindex maximizing windows
@deffn Command maximize-window &optional window
661 662 663 664
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.
665 666 667 668
@end deffn

@cindex minimizing windows
@deffn Command minimize-window &optional window
669 670 671 672
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.
673 674 675
@end deffn


Glenn Morris's avatar
Glenn Morris committed
676 677 678 679 680
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

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

684
@deffn Command split-window &optional window size side
685 686 687 688 689
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.

690
The optional second argument @var{size} determines the sizes of
691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723
@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.

724 725
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
726
@code{ignore-window-parameters} is @code{nil}.  If the value of
727 728 729 730 731 732 733
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}.
734
@end deffn
Glenn Morris's avatar
Glenn Morris committed
735

736 737 738 739 740
  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
741
@code{(split-window W4)} yields this window configuration:
742 743 744 745 746 747 748 749

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
750 751
    ||_________________W4_________________||
    | ____________________________________ |
752 753 754 755 756 757 758 759 760
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

761 762 763 764 765
@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}.
766

767 768
  Next, we call @code{(split-window W3 nil 'left)}, passing the
internal window @var{W3} as the argument.  The result:
769 770 771 772 773

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
774 775 776 777 778 779 780 781 782 783
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
784 785 786 787
    |__________________W1__________________|
@end group
@end smallexample

788
@noindent
789 790 791
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.
792

793
@defopt window-combination-resize
794
If this variable is @code{nil}, @code{split-window} can only split a
795 796 797 798 799 800 801 802 803 804 805 806 807 808
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} (see below).
Martin Rudalics's avatar
Martin Rudalics committed
809
@end defopt
810

811 812 813
  To illustrate the effect of @code{window-combination-resize},
consider the following window configuration:

814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

834 835 836 837
@noindent
If @code{window-combination-resize} is @code{nil}, splitting window
@code{W3} leaves the size of @code{W2} unchanged:

838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

858
@noindent
859 860 861
If @code{window-combination-resize} is @code{t}, splitting @code{W3}
instead leaves all three live windows with approximately the same
height:
862

863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

883
@defopt window-combination-limit
884 885 886 887 888 889 890 891
If the value of this variable is @code{t}, the @code{split-window}
function always creates a new internal window.  If the value is
@code{nil}, the new live window is allowed to share the existing
parent window, if one exists, provided the split occurs in the same
direction as the existing window combination (otherwise, a new
internal window is created anyway).  The default is @code{nil}.  Other
values are reserved for future use.

892 893 894
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).
895 896 897 898 899 900

Furthermore, @code{split-window} calls
@code{set-window-combination-limit} on the newly-created internal
window, recording the current value of this variable.  This affects
how the window tree is rearranged when the child windows are deleted
(see below).
901 902
@end defopt

903
@cindex window combination limit
904
@defun set-window-combination-limit window limit
905
This functions sets the @dfn{combination limit} of the window
906
@var{window} to @var{limit}.  This value can be retrieved via the
907 908
function @code{window-combination-limit}.  See below for its effects;
note that it is only meaningful for internal windows.  The
909 910 911
@code{split-window} function automatically calls this function, passing
the value of the variable @code{window-combination-limit} as
@var{limit}.
912 913
@end defun

914 915 916 917 918 919
@defun window-combination-limit window
This function returns the combination limit for @var{window}.

The combination limit is meaningful only for an internal window.  If
it is @code{nil}, then Emacs is allowed to automatically delete
@var{window}, in response to a window deletion, in order to group the
920 921 922 923
child windows of @var{window} with its sibling windows to form a new
window combination.  If the combination limit is @code{t}, the child
windows of @var{window} are never automatically re-combined with its
siblings.
924 925
@end defun

926 927 928 929
  To illustrate the effect of @code{window-combination-limit},
consider the following configuration (throughout this example, we will
assume that @code{window-combination-resize} is @code{nil}):

930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

950 951 952
@noindent
If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
into two windows, one above the other, yields
953 954 955 956 957 958 959 960 961 962 963 964 965 966

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
967
    ||                                    ||
968 969 970 971 972 973
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

974 975 976 977
@noindent
The newly-created window, @code{W4}, shares the same internal window
@code{W1}.  If @code{W4} is resized, it is allowed to resize the other
live window, @code{W3}.
978

979 980
  If @code{window-combination-limit} is @code{t}, splitting @code{W2}
in the initial configuration would instead have produced this:
981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001

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

@end group
@end smallexample

1002 1003 1004 1005 1006
@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 resizing @code{W4} will resize
@code{W2}, leaving @code{W3} unaffected.
1007

1008 1009
  For interactive use, Emacs provides two commands which always split
the selected window.  These call @code{split-window} internally.
1010

1011 1012 1013 1014 1015 1016
@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
1017

1018
@deffn Command split-window-below &optional size
1019 1020 1021 1022
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.
Glenn Morris's avatar
Glenn Morris committed
1023 1024 1025
@end deffn

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

1029 1030 1031 1032 1033 1034
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.
Glenn Morris's avatar
Glenn Morris committed
1035 1036 1037 1038 1039 1040
@end defopt

@node Deleting Windows
@section Deleting Windows
@cindex deleting windows

1041 1042 1043 1044 1045 1046 1047 1048
  @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}).
Glenn Morris's avatar
Glenn Morris committed
1049 1050

@deffn Command delete-window &optional window
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064
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{Splitting Windows}.

The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
1065
@code{ignore-window-parameters} is @code{nil}.  If the value of
1066 1067 1068 1069 1070 1071 1072
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}.
Glenn Morris's avatar
Glenn Morris committed
1073 1074 1075
@end deffn

@deffn Command delete-other-windows &optional window
1076 1077 1078 1079 1080 1081
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
1082
@code{ignore-window-parameters} is @code{nil}.  If the value of
1083 1084 1085 1086 1087 1088 1089
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}.
Glenn Morris's avatar
Glenn Morris committed
1090 1091
@end deffn

1092
@deffn Command delete-windows-on &optional buffer-or-name frame
1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105
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:
Glenn Morris's avatar
Glenn Morris committed
1106 1107

@itemize @bullet
1108 1109 1110 1111 1112 1113 1114 1115 1116 1117
@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
1118 1119
@end itemize

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

Glenn Morris's avatar
Glenn Morris committed
1126 1127 1128 1129 1130
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1131 1132
This function makes @var{window} the selected window, as well as the
window selected within its frame (@pxref{Basic Windows}).
1133
@var{window} must be a live window.  Unless @var{window} already is the
1134 1135 1136 1137 1138 1139 1140 1141
selected window, its buffer becomes the current buffer (@pxref{Buffers
and Windows}).  The return value is @var{window}.

By default, this function also moves @var{window}'s selected 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
1142 1143
@end defun

1144
@cindex most recently selected windows
1145
  The sequence of calls to @code{select-window} with a non-@code{nil}
1146 1147
@var{norecord} argument determines an ordering of windows by their
selection time.  The function @code{get-lru-window} can be used to
1148 1149
retrieve the least recently selected live window (@pxref{Cyclic Window
Ordering}).
1150

Glenn Morris's avatar
Glenn Morris committed
1151 1152 1153 1154 1155 1156 1157
@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,
1158
arrangement or contents of windows; therefore, if @var{forms} change
Martin Rudalics's avatar
Martin Rudalics committed
1159 1160 1161 1162 1163 1164 1165 1166 1167
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
1168 1169 1170
@end defmac

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1171 1172 1173
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
1174
you deliberately change them within @var{forms}; for example, by calling
1175
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1176

1177 1178
This macro does not change the order of recently selected windows or
the buffer list.
1179
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1180

1181 1182 1183 1184
@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
1185 1186
@end defun

1187
@defun set-frame-selected-window frame window &optional norecord
1188
This function makes @var{window} the window selected within the frame
1189 1190 1191 1192
@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.
1193

1194 1195
If @var{frame} is the selected frame, this makes @var{window} the
selected window.
Glenn Morris's avatar
Glenn Morris committed
1196

1197 1198 1199 1200
If the optional argument @var{norecord} is non-@code{nil}, this
function does not alter the list of most recently selected windows,
nor the buffer list.
@end defun
Glenn Morris's avatar
Glenn Morris committed
1201 1202 1203 1204 1205 1206 1207

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

1208
  When you use the command @kbd{C-x o} (@code{other-window}) to select
1209
some other window, it moves through live windows in a specific order.
1210 1211
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
1212

1213 1214 1215 1216 1217
  The ordering is determined by a depth-first traversal of the frame's
window tree, retrieving the live windows which are the leaf nodes of
the tree (@pxref{Windows and Frames}).  If the minibuffer is active,
the minibuffer window is included too.  The ordering is cyclic, so the
last window in the sequence is followed by the first one.
Glenn Morris's avatar
Glenn Morris committed
1218

Juri Linkov's avatar
Juri Linkov committed
1219
@defun next-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1220
@cindex minibuffer window, and @code{next-window}
1221 1222 1223
This function returns a live window, the one following @var{window} in
the cyclic ordering of windows.  @var{window} should be a live window;
if omitted or @code{nil}, it defaults to the selected window.
Glenn Morris's avatar
Glenn Morris committed
1224

1225
The optional argument @var{minibuf} specifies whether minibuffer windows
1226
should be included in the cyclic ordering.  Normally, when @var{minibuf}
1227 1228 1229 1230
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
1231

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

1236
The optional argument @var{all-frames} specifies which frames to
1237
consider:
Glenn Morris's avatar
Glenn Morris committed
1238

1239
@itemize @bullet
Glenn Morris's avatar
Glenn Morris committed
1240
@item @code{nil}
1241 1242 1243
means to consider windows on @var{window}'s frame.  If the minibuffer
window is considered (as specified by the @var{minibuf} argument),
then frames that share the minibuffer window are considered too.
Glenn Morris's avatar
Glenn Morris committed
1244 1245

@item @code{t}
1246
means to consider windows on all existing frames.
Glenn Morris's avatar
Glenn Morris committed
1247 1248

@item @code{visible}
1249
means to consider windows on all visible frames.
Glenn Morris's avatar
Glenn Morris committed
1250 1251

@item 0
1252
means to consider windows on all visible or iconified frames.
Glenn Morris's avatar