windows.texi 146 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Windows
Glenn Morris's avatar
Glenn Morris committed
7 8
@chapter Windows

9 10 11 12
This chapter describes the functions and variables related to Emacs
windows.  @xref{Frames}, for how windows are assigned an area of screen
available for Emacs to use.  @xref{Display}, for information on how text
is displayed in windows.
Glenn Morris's avatar
Glenn Morris committed
13 14 15

@menu
* Basic Windows::           Basic information on using windows.
16 17 18
* Windows and Frames::      Relating windows to the frame they appear on.
* Window Sizes::            Accessing a window's size.
* Resizing Windows::        Changing the sizes of windows.
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
@defun windowp object
This function returns @code{t} if @var{object} is a window (whether or
81
not it displays a buffer).  Otherwise, it returns @code{nil}.
82
@end defun
83

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

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

93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
@cindex internal windows
The windows in each frame are organized into a @dfn{window tree}.
@xref{Windows and Frames}.  The leaf nodes of each window tree are live
windows---the ones actually displaying buffers.  The internal nodes of
the window tree are @dfn{internal windows}, which are not live.

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

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

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

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

@node Windows and Frames
@section Windows and Frames

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

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

144 145 146 147
@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.
148

149 150 151 152 153 154
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.
155

Martin Rudalics's avatar
Martin Rudalics committed
156 157 158 159
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.
160 161 162
@end defun

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

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

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

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

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

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

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

@end group
@end smallexample

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

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

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

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

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

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

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

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

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

@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
323 324 325
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.
326 327

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

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

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

348
  The following schematic shows the structure of a live window:
349 350 351

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

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

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

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

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

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

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

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

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

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

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

480 481 482
@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.
483 484
@end defun

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

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

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

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
511 512 513 514 515
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.
516

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

522 523 524 525 526 527
  @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.
528 529 530 531 532 533 534 535

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

536 537 538 539 540 541 542 543 544 545
  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.
546

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

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.
572 573 574
@end defun

@defun window-resize window delta &optional horizontal ignore
575 576 577 578 579 580 581 582 583 584 585 586
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.

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

595 596 597
@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.
598 599 600

@defun adjust-window-trailing-edge window delta &optional horizontal
This function moves @var{window}'s bottom edge by @var{delta} lines.
601 602 603
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.
604

605 606 607 608
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.
609 610

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

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

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

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

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

@cindex maximizing windows
@deffn Command maximize-window &optional window
666 667 668 669
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.
670 671 672 673
@end deffn

@cindex minimizing windows
@deffn Command minimize-window &optional window
674 675 676 677
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.
678 679 680
@end deffn


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

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

689
@deffn Command split-window &optional window size side
690 691 692 693 694
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.

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

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

741 742 743 744 745
  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
746
@code{(split-window W4)} yields this window configuration:
747 748 749 750 751 752 753 754

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

@end group
@end smallexample

766 767 768 769 770
@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}.
771

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

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

793
@noindent
794 795 796
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.
797

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

816 817 818
  To illustrate the effect of @code{window-combination-resize},
consider the following window configuration:

819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

839 840 841 842
@noindent
If @code{window-combination-resize} is @code{nil}, splitting window
@code{W3} leaves the size of @code{W2} unchanged:

843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

863
@noindent
864 865 866
If @code{window-combination-resize} is @code{t}, splitting @code{W3}
instead leaves all three live windows with approximately the same
height:
867

868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

@end group
@end smallexample

888
@defopt window-combination-limit
889 890 891 892 893 894 895 896
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.

897 898 899
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).
900 901 902 903 904 905

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).
906 907
@end defopt

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

919 920 921 922 923 924
@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
925 926 927 928
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.
929 930
@end defun

931 932 933 934
  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}):

935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954
@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

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

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
972
    ||                                    ||
973 974 975 976 977 978
    ||_________________W3_________________||
    |__________________W1__________________|

@end group
@end smallexample

979 980 981 982
@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}.
983

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

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

@end group
@end smallexample

1007 1008 1009 1010 1011
@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.
1012

1013 1014
  For interactive use, Emacs provides two commands which always split
the selected window.  These call @code{split-window} internally.
1015

1016 1017 1018 1019 1020 1021
@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
1022

1023
@deffn Command split-window-below &optional size
1024 1025 1026 1027
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
1028 1029 1030
@end deffn

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

1034 1035 1036 1037 1038 1039
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
1040 1041 1042 1043 1044 1045
@end defopt

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

1046 1047 1048 1049 1050 1051 1052 1053
  @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
1054 1055

@deffn Command delete-window &optional window
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
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
1070
@code{ignore-window-parameters} is @code{nil}.  If the value of
1071 1072 1073 1074 1075 1076 1077
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
1078 1079 1080
@end deffn

@deffn Command delete-other-windows &optional window
1081 1082 1083 1084 1085 1086
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
1087
@code{ignore-window-parameters} is @code{nil}.  If the value of
1088 1089 1090 1091 1092 1093 1094
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
1095 1096
@end deffn

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

@itemize @bullet
1113 1114 1115 1116 1117 1118 1119 1120 1121 1122
@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
1123 1124
@end itemize

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

Glenn Morris's avatar
Glenn Morris committed
1131 1132 1133 1134 1135
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window

@defun select-window window &optional norecord
1136
This function makes @var{window} the selected window, as well as the
1137 1138 1139 1140 1141 1142 1143 1144 1145
window selected within its frame (@pxref{Basic Windows}).  @var{window}
must be a live window.  This function makes also @var{window}'s buffer
current (@pxref{Buffers and Windows}).  The return value is
@var{window}.

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

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

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

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

1181 1182
This macro does not change the order of recently selected windows or
the buffer list.
1183
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1184

1185 1186 1187 1188
@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
1189 1190
@end defun

1191
@defun set-frame-selected-window frame window &optional norecord
1192
This function makes @var{window} the window selected within the frame
1193 1194 1195 1196
@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.
1197

1198 1199
If @var{frame} is the selected frame, this makes @var{window} the
selected window.
Glenn Morris's avatar
Glenn Morris committed
1200

1201 1202 1203 1204
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
1205 1206 1207 1208 1209 1210 1211

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

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

1217 1218 1219 1220 1221
  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
1222

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

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

1236 1237 1238
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
1239

1240
The optional argument @var{all-frames} specifies which frames to
1241
consider:
Glenn Morris's avatar
Glenn Morris committed
1242

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