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
@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
  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).
71
When Emacs is run on a text terminal, the frame fills the entire
72
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
@cindex window selected within a frame
114 115 116 117 118 119 120 121 122
  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}.
123 124

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

@node Windows and Frames
@section Windows and Frames

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

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

140 141 142 143
@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.
144

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

Martin Rudalics's avatar
Martin Rudalics committed
152 153 154 155
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.
156 157 158
@end defun

@cindex window tree
159 160 161 162 163 164 165 166 167 168 169 170 171 172
@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.
173 174

@defun frame-root-window &optional frame-or-window
175 176 177 178 179
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.
180 181
@end defun

182 183 184 185 186 187 188 189 190 191 192 193
@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}.
194 195 196

@cindex parent window
@defun window-parent &optional window
197 198 199 200
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).
201 202
@end defun

203 204 205 206 207 208 209 210 211 212
  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.
213 214 215 216

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
217 218 219 220 221 222
  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:
223 224 225 226 227 228

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

@end group
@end smallexample

243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258
@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}.
259 260
@end defun

261 262 263 264 265
@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}.
266 267 268
@end defun

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

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

280 281 282
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.
283 284 285
@end defun

@defun window-next-sibling &optional window
286 287 288 289
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.
290 291 292
@end defun

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

299 300 301 302 303
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}).
304

305 306
  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:
307 308 309 310 311 312 313 314 315 316 317 318

@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
319 320 321
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.
322 323

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

327 328 329 330 331 332 333 334 335 336
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}).
337 338 339 340 341 342 343
@end defun

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

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

@smallexample
@group
348 349
         _________________________________________
      ^ |______________ Header Line_______________|
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364
      | |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
365
@cindex text area of a window
366
@cindex body of a window
367 368 369 370 371 372 373 374 375 376 377 378
  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
379
a window.  Except where noted, Emacs reports window heights and widths
380 381 382 383 384 385
as integer numbers of lines and columns respectively.  On a graphical
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.
386 387 388 389 390 391 392

@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
393 394 395 396 397 398 399
  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}).
400 401

@defun window-total-height &optional window
402 403 404 405
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.
406 407 408
@end defun

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

415 416 417 418 419 420
@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}.
421 422 423
@end defun

@cindex full-width window
424 425 426 427 428 429 430 431 432 433
@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
434 435

@defun window-full-width-p &optional window
436 437 438 439
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.
440 441 442 443 444 445 446 447
@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
448 449 450 451
  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.
452 453

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

@end group
@end smallexample

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

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

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

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

794
@defopt window-combination-resize
795
If this variable is @code{nil}, @code{split-window} can only split a
796 797 798 799 800 801 802 803 804 805 806 807 808 809
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
810
@end defopt
811

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

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

@end group
@end smallexample

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

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

@end group
@end smallexample

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

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

@end group
@end smallexample

884
@defopt window-combination-limit
885 886 887 888 889 890 891 892
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.

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

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).
902 903
@end defopt

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

915 916 917 918 919 920
@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
921 922 923 924
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.
925 926
@end defun

927 928 929 930
  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}):

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

@end group
@end smallexample

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

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

@end group
@end smallexample

975 976 977 978
@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}.
979

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

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

@end group
@end smallexample

1003 1004 1005 1006 1007
@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.
1008

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

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

1019
@deffn Command split-window-below &optional size
1020 1021 1022 1023
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
1024 1025 1026
@end deffn

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

1030 1031 1032 1033 1034 1035
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
1036 1037 1038 1039 1040 1041
@end defopt

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

1042 1043 1044 1045 1046 1047 1048 1049
  @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
1050 1051

@deffn Command delete-window &optional window
1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073
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
@code{ignore-window-parameters} is non-@code{nil}.  If the value of
the @code{delete-window} window parameter is @code{t}, this function
ignores all other window parameters.  Otherwise, if the value of the
@code{delete-window} window parameter is a function, that function is
called with the argument @var{window}, in lieu of the usual action of
@code{delete-window}.  Otherwise, this function obeys the
@code{window-atom} or @code{window-side} window parameter, if any.
@xref{Window Parameters}.
Glenn Morris's avatar
Glenn Morris committed
1074 1075 1076
@end deffn

@deffn Command delete-other-windows &optional window
1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090
This function makes @var{window} fill its frame, by deleting other
windows as necessary.  If @var{window} is omitted or @code{nil}, it
defaults to the selected window.  The return value is @code{nil}.

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

1093
@deffn Command delete-windows-on &optional buffer-or-name frame
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106
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
1107 1108

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

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

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

@defun select-window window &optional norecord
1132 1133
This function makes @var{window} the selected window, as well as the
window selected within its frame (@pxref{Basic Windows}).
1134
@var{window} must be a live window.  Unless @var{window} already is the
1135 1136 1137 1138 1139 1140 1141 1142
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
1143 1144
@end defun

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

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

@defmac with-selected-window window forms@dots{}
Martin Rudalics's avatar
Martin Rudalics committed
1172 1173 1174 1175
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
1176
@code{select-window} with argument @var{norecord} @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1177

1178 1179 1180
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
1181

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

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

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

1198 1199 1200 1201
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
1202 1203 1204 1205 1206 1207 1208

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

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

1214 1215 1216 1217 1218
  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
1219

Juri Linkov's avatar
Juri Linkov committed
1220
@defun next-window &optional window minibuf all-frames
Glenn Morris's avatar
Glenn Morris committed
1221
@cindex minibuffer window, and @code{next-window}
1222 1223 1224
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
1225

1226 1227 1228 1229 1230 1231
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
1232

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

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

1240
@itemize @bullet
Glenn Morris's avatar
Glenn Morris committed
1241
@item @code{nil}
1242 1243 1244
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
1245 1246

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

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

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

1255
@item A frame
1256
means to consider windows on that specific frame.
Glenn Morris's avatar
Glenn Morris committed
1257

1258
@item Anything else
1259
means to consider windows on @var{window}'s frame, and no others.
1260
@end itemize
Glenn Morris's avatar
Glenn Morris committed
1261

1262 1263 1264
If more than one frame is considered, the cyclic ordering is obtained
by appending the orderings for those frames, in the same order as the
list of all live frames (@pxref{Finding All Frames}).
Juri Linkov's avatar
Juri Linkov committed
1265
@end defun
Glenn Morris's avatar
Glenn Morris committed
1266

Juri Linkov's avatar
Juri Linkov committed
1267
@defun previous-window &optional window minibuf all-frames
1268 1269