windows.texi 258 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.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software
4
@c Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Windows
Glenn Morris's avatar
Glenn Morris committed
7 8
@chapter Windows

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

@menu
* Basic Windows::           Basic information on using windows.
16 17 18
* Windows and Frames::      Relating windows to the frame they appear on.
* Window Sizes::            Accessing a window's size.
* Resizing Windows::        Changing the sizes of windows.
19
* Preserving Window Sizes:: Preserving the size of windows.
20
* Splitting Windows::       Creating a new window.
21 22 23
* Deleting Windows::        Removing a window from its frame.
* Recombining Windows::     Preserving the frame layout when splitting and
                              deleting windows.
Glenn Morris's avatar
Glenn Morris committed
24 25 26
* 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.
27
* Switching Buffers::       Higher-level functions for switching to a buffer.
28
* Displaying Buffers::      Displaying a buffer in a suitable window.
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.
34
* Side Windows::            Special windows on a frame's sides.
35
* Atomic Windows::          Preserving parts of the window layout.
Glenn Morris's avatar
Glenn Morris committed
36
* Window Point::            Each window has its own location of point.
Martin Rudalics's avatar
Martin Rudalics committed
37 38
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
Glenn Morris's avatar
Glenn Morris committed
39 40 41 42
* Textual Scrolling::       Moving text up and down through the window.
* Vertical Scrolling::      Moving the contents up and down on the window.
* Horizontal Scrolling::    Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
43
* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
Glenn Morris's avatar
Glenn Morris committed
44
* Window Configurations::   Saving and restoring the state of the screen.
Martin Rudalics's avatar
Martin Rudalics committed
45
* Window Parameters::       Associating additional information with windows.
Glenn Morris's avatar
Glenn Morris committed
46 47 48 49 50
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
@end menu

51

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

56 57 58
A @dfn{window} is an area of the screen that 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
59 60

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

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

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

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

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

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

97 98 99 100 101 102 103 104
@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
105
window can be @dfn{deleted}, i.e., removed from its frame
106 107 108 109 110 111
(@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
112 113 114 115 116 117
@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.
118 119 120
@end defun

@cindex selected window
121
@cindex window selected within a frame
122 123 124 125
  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
126 127 128 129 130 131 132
appears (@pxref{Cursor Parameters}).  Keyboard input that inserts or
deletes text is also normally directed to this window.   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}.
133 134

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

139 140 141 142 143 144 145 146
@anchor{Window Group}Sometimes several windows collectively and
cooperatively display a buffer, for example, under the management of
Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
display a bigger portion of the buffer than one window could alone.
It is often useful to consider such a @dfn{window group} as a single
entity.  Several functions such as @code{window-group-start}
(@pxref{Window Start and End}) allow you to do this by supplying, as
an argument, one of the windows as a stand in for the whole group.
147 148 149 150 151 152 153 154 155 156 157 158 159 160

@defun selected-window-group
@vindex selected-window-group-function
When the selected window is a member of a group of windows, this
function returns a list of the windows in the group, ordered such that
the first window in the list is displaying the earliest part of the
buffer, and so on.  Otherwise the function returns a list containing
just the selected window.

The selected window is considered part of a group when the buffer
local variable @code{selected-window-group-function} is set to a
function.  In this case, @code{selected-window-group} calls it with no
arguments and returns its result (which should be the list of windows
in the group).
161 162 163 164 165
@end defun

@node Windows and Frames
@section Windows and Frames

166
Each window belongs to exactly one frame (@pxref{Frames}).
167

168
@defun window-frame &optional window
169 170 171
This function returns the frame that the window @var{window} belongs
to.  If @var{window} is @code{nil}, it defaults to the selected
window.
172 173
@end defun

174 175 176 177
@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.
178

179 180 181 182 183 184
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.
185

Martin Rudalics's avatar
Martin Rudalics committed
186 187 188 189
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.
190 191 192
@end defun

@cindex window tree
193 194 195 196 197 198 199 200
@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.

201 202 203 204 205 206 207
  A minibuffer window (@pxref{Minibuffer Windows}) that is not alone
on its frame does not have a parent window, so it strictly speaking is
not part of its frame's window tree.  Nonetheless, it is a sibling
window of the frame's root window, and thus can be reached via
@code{window-next-sibling}.  Also, the function @code{window-tree}
described at the end of this section lists the minibuffer window
alongside the actual window tree.
208 209

@defun frame-root-window &optional frame-or-window
210 211 212 213 214
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.
215 216
@end defun

217 218 219 220 221 222 223 224 225 226 227 228
@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}.
229 230 231

@cindex parent window
@defun window-parent &optional window
232 233 234
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
235
(i.e., it is a minibuffer window or the root window of its frame).
236 237
@end defun

238 239 240 241 242 243 244 245 246 247
  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.
248 249 250 251

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
252 253 254 255 256 257
  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:
258 259 260 261 262 263

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
264 265 266
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
267 268 269
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
270
    ||      |||                          |||
271 272 273 274 275 276 277
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

278
@noindent
279
The root window of this frame is an internal window, @var{W1}.  Its
280
child windows form a horizontal combination, consisting of the live
281 282 283
window @var{W2} and the internal window @var{W3}.  The child windows
of @var{W3} form a vertical combination, consisting of the live
windows @var{W4} and @var{W5}.  Hence, the live windows in this
284
window tree are @var{W2}, @var{W4}, and @var{W5}.
285 286 287 288

  The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.

289
@defun window-top-child &optional window
290 291 292 293
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}.
294 295
@end defun

296
@defun window-left-child &optional window
297 298 299 300
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}.
301 302 303
@end defun

@defun window-child window
304 305 306 307
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}.
308 309
@end defun

310
@defun window-combined-p &optional window horizontal
311 312
This function returns a non-@code{nil} value if and only if
@var{window} is part of a vertical combination.  If @var{window} is
313
omitted or @code{nil}, it defaults to the selected one.
314

315 316 317
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.
318 319 320
@end defun

@defun window-next-sibling &optional window
321 322 323 324
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.
325 326 327
@end defun

@defun window-prev-sibling &optional window
328 329 330 331
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.
332 333
@end defun

334 335
The functions @code{window-next-sibling} and
@code{window-prev-sibling} should not be confused with the functions
336 337
@code{next-window} and @code{previous-window}, which return the next
and previous window, respectively, in the cyclic ordering of windows
338
(@pxref{Cyclic Window Ordering}).
339

340 341
  The following functions can be useful to locate a window within its
frame.
342 343 344 345 346 347 348 349

@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
350
@code{(frame-first-window)} returns @var{W2}.
351 352
@end defun

353 354 355 356 357 358 359 360 361 362 363 364 365 366
@defun window-at-side-p &optional window side
This function returns @code{t} if @var{window} is located at
@var{side} of its containing frame.  The argument @var{window} must be
a valid window and defaults to the selected one.  The argument
@var{side} can be any of the symbols @code{left}, @code{top},
@code{right} or @code{bottom}.  The default value @code{nil} is
handled like @code{bottom}.

Note that this function disregards the minibuffer window
(@pxref{Minibuffer Windows}).  Hence, with @var{side} equal to
@code{bottom} it may return @code{t} also when the minibuffer window
appears right below @var{window}.
@end defun

367
@cindex window in direction
368
@defun window-in-direction direction &optional window ignore sign wrap mini
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
This function returns the nearest live window in direction
@var{direction} as seen from the position of @code{window-point} in
window @var{window}.  The argument @var{direction} must be one of
@code{above}, @code{below}, @code{left} or @code{right}.  The optional
argument @var{window} must denote a live window and defaults to the
selected one.

This function does not return a window whose @code{no-other-window}
parameter is non-@code{nil} (@pxref{Window Parameters}).  If the nearest
window's @code{no-other-window} parameter is non-@code{nil}, this
function tries to find another window in the indicated direction whose
@code{no-other-window} parameter is @code{nil}.  If the optional
argument @var{ignore} is non-@code{nil}, a window may be returned even
if its @code{no-other-window} parameter is non-@code{nil}.

384 385 386 387 388 389 390 391
If the optional argument @var{sign} is a negative number, it means to
use the right or bottom edge of @var{window} as reference position
instead of @code{window-point}.  If @var{sign} is a positive number, it
means to use the left or top edge of @var{window} as reference position.

If the optional argument @var{wrap} is non-@code{nil}, this means to
wrap @var{direction} around frame borders.  For example, if @var{window}
is at the top of the frame and @var{direction} is @code{above}, then
Martin Rudalics's avatar
Martin Rudalics committed
392 393
this function usually returns the frame's minibuffer window if it's
active and a window at the bottom of the frame otherwise.
394 395 396

If the optional argument @var{mini} is @code{nil}, this means to return
the minibuffer window if and only if it is currently active.  If
Martin Rudalics's avatar
Martin Rudalics committed
397 398 399
@var{mini} is non-@code{nil}, this function may return the minibuffer
window even when it's not active.  However, if @var{wrap} is
non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
400

401 402 403 404 405 406
If it doesn't find a suitable window, this function returns
@code{nil}.

Don't use this function to check whether there is @emph{no} window in
@var{direction}.  Calling @code{window-at-side-p} described above is a
much more efficient way to do that.
407 408
@end defun

409 410
The following function allows the entire window tree of a frame to be
retrieved:
411

412
@defun window-tree &optional frame
413 414 415
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.
416 417

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

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

433

434 435 436 437 438
@node Window Sizes
@section Window Sizes
@cindex window size
@cindex size of window

439
  The following schematic shows the structure of a live window:
440 441 442

@smallexample
@group
443 444
        ____________________________________________
       |______________ Header Line ______________|RD| ^
445
     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
446 447 448 449 450 451
     | |  |  |  |                       |  |  |  |  | |
Window |  |  |  |       Text Area       |  |  |  |  | Window
Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
Height |  |  |  |                       |  |  |  |  | Height
     | |  |  |  |<- Window Body Width ->|  |  |  |  | |
     v |__|__|__|_______________________|__|__|__|  | |
452
       |_________ Horizontal Scroll Bar _________|  | |
453 454 455
       |_______________ Mode Line _______________|__| |
       |_____________ Bottom Divider _______________| v
        <---------- Window Total Width ------------>
456 457 458 459 460

@end group
@end smallexample

@cindex window body
461
@cindex text area of a window
462
@cindex body of a window
463
  At the center of the window is the @dfn{text area}, or @dfn{body},
464 465
where the buffer text is displayed.  The text area can be surrounded by
a series of optional areas.  On the left and right, from innermost to
466 467 468 469 470
outermost, these are the left and right fringes, denoted by LF and RF
(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
the schematic (@pxref{Display Margins}); the left or right vertical
scroll bar, only one of which is present at any time, denoted by LS and
RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
471
(@pxref{Window Dividers}).  At the top of the window is the header line
472 473 474
(@pxref{Header Lines}).  At the bottom of the window are the horizontal
scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
Format}); and the bottom divider (@pxref{Window Dividers}).
475 476 477 478 479

  Emacs provides miscellaneous functions for finding the height and
width of a window.  The return value of many of these functions can be
specified either in units of pixels or in units of lines and columns.
On a graphical display, the latter actually correspond to the height and
Paul Eggert's avatar
Paul Eggert committed
480
width of a default character specified by the frame's default font
481
as returned by @code{frame-char-height} and @code{frame-char-width}
482 483
(@pxref{Frame Font}).  Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
484 485
that window may differ from the actual number of text lines or columns
displayed within it.
486

487 488 489
@cindex window height
@cindex height of a window
@cindex total height of a window
490
  The @dfn{total height} of a window is the number of lines comprising
491 492
the window's body, the header line, the horizontal scroll bar, the mode
line and the bottom divider (if any).
493

494
@defun window-total-height &optional window round
495
This function returns the total height, in lines, of the window
496 497 498 499
@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.

500
  If a window's pixel height is not an integral multiple of its frame's
501 502 503 504 505
default character height, the number of lines occupied by the window is
rounded internally.  This is done in a way such that, if the window is a
parent window, the sum of the total heights of all its child windows
internally equals the total height of their parent.  This means that
although two windows have the same pixel height, their internal total
506 507
heights may differ by one line.  This means also, that if window is
vertically combined and has a next sibling, the topmost row of that
508 509 510
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})

511
  If the optional argument @var{round} is @code{ceiling}, this
512
function returns the smallest integer larger than @var{window}'s pixel
513 514 515 516
height divided by the character height of its frame; if it is
@code{floor}, it returns the largest integer smaller than said value;
with any other @var{round} it returns the internal value of
@var{windows}'s total height.
517 518
@end defun

519 520 521 522 523 524 525
@cindex window width
@cindex width of a window
@cindex total width of a window
The @dfn{total width} of a window is the number of lines comprising the
window's body, its margins, fringes, scroll bars and a right divider (if
any).

526
@defun window-total-width &optional window round
527
This function returns the total width, in columns, of the window
528 529 530 531
@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.

532
  If a window's pixel width is not an integral multiple of its frame's
533 534 535 536 537 538
character width, the number of lines occupied by the window is rounded
internally.  This is done in a way such that, if the window is a parent
window, the sum of the total widths of all its children internally
equals the total width of their parent.  This means that although two
windows have the same pixel width, their internal total widths may
differ by one column.  This means also, that if this window is
539
horizontally combined and has a next sibling, the leftmost column of
540
that sibling can be calculated as the sum of this window's leftmost
541 542
column and total width (@pxref{Coordinates and Windows}).  The optional
argument @var{round} behaves as it does for @code{window-total-height}.
543
@end defun
544

545
@defun window-total-size &optional window horizontal round
546 547 548 549 550
This function returns either the total height in lines or the total
width in columns 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}.  The optional
551
argument @var{round} behaves as it does for @code{window-total-height}.
552 553 554 555 556 557 558 559 560 561 562 563 564
@end defun

The following two functions can be used to return the total size of a
window in units of pixels.

@cindex window pixel height
@cindex pixel height of a window
@cindex total pixel height of a window

@defun window-pixel-height &optional window
This function returns the total height of window @var{window} in pixels.
@var{window} must be a valid window and defaults to the selected one.

565 566 567 568
The return value includes mode and header line, a horizontal scroll bar
and a bottom divider, if any.  If @var{window} is an internal window,
its pixel height is the pixel height of the screen areas spanned by its
children.
569 570
@end defun

571 572 573 574 575 576
@defun window-pixel-height-before-size-change &optional Lisp_Object &optional window
This function returns the height of window @var{window} in pixels at the
time @code{window-size-change-functions} was run for the last time on
@var{window}'s frame (@pxref{Window Hooks}).
@end defun

577 578 579
@cindex window pixel width
@cindex pixel width of a window
@cindex total pixel width of a window
580

581
@defun window-pixel-width &optional window
582 583 584 585 586 587 588
This function returns the width of window @var{window} in pixels.
@var{window} must be a valid window and defaults to the selected one.

The return value includes the fringes and margins of @var{window} as
well as any vertical dividers or scroll bars belonging to @var{window}.
If @var{window} is an internal window, its pixel width is the width of
the screen areas spanned by its children.
589 590
@end defun

591 592 593 594 595 596
@defun window-pixel-width-before-size-change &optional Lisp_Object &optional window
This function returns the width of window @var{window} in pixels at the
time @code{window-size-change-functions} was run for the last time on
@var{window}'s frame (@pxref{Window Hooks}).
@end defun

597
@cindex full-width window
598 599 600 601 602
@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
603 604 605 606 607 608
This function returns non-@code{nil} if @var{window} has no other window
above or below it in its frame.  More precisely, this means that the
total height of @var{window} equals the total height of the root window
on that frame.  The minibuffer window does not count in this regard.  If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
609
@end defun
610 611

@defun window-full-width-p &optional window
612
This function returns non-@code{nil} if @var{window} has no other
613
window to the left or right in its frame, i.e., its total width equals
614 615
that of the root window on that frame.  If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
616 617 618 619
@end defun

@cindex window body height
@cindex body height of a window
620
The @dfn{body height} of a window is the height of its text area, which
621 622
does not include a mode or header line, a horizontal scroll bar, or a
bottom divider.
623

624
@defun window-body-height &optional window pixelwise
625 626 627 628 629 630 631 632 633 634 635 636
This function returns the height, in lines, of the body of window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.

If the optional argument @var{pixelwise} is non-@code{nil}, this
function returns the body height of @var{window} counted in pixels.

If @var{pixelwise} is @code{nil}, the return value is rounded down to
the nearest integer, if necessary.  This means that if a line at the
bottom of the text area is only partially visible, that line is not
counted.  It also means that the height of a window's body can never
exceed its total height as returned by @code{window-total-height}.
637 638
@end defun

639
@cindex window body width
640 641 642
@cindex body width of a window
The @dfn{body width} of a window is the width of its text area, which
does not include the scroll bar, fringes, margins or a right divider.
643 644 645 646 647 648
Note that when one or both fringes are removed (by setting their width
to zero), the display engine reserves two character cells, one on each
side of the window, for displaying the continuation and truncation
glyphs, which leaves 2 columns less for text display.  (The function
@code{window-max-chars-per-line}, described below, takes this
peculiarity into account.)
649

650 651 652 653 654 655 656 657 658 659 660 661 662
@defun window-body-width &optional window pixelwise
This function returns the width, in columns, of the body of window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.

If the optional argument @var{pixelwise} is non-@code{nil}, this
function returns the body width of @var{window} in units of pixels.

If @var{pixelwise} is @code{nil}, the return value is rounded down to
the nearest integer, if necessary.  This means that if a column on the
right of the text area is only partially visible, that column is not
counted.  It also means that the width of a window's body can never
exceed its total width as returned by @code{window-total-width}.
663 664
@end defun

665 666
@cindex window body size
@cindex body size of a window
667 668 669 670 671 672
@defun window-body-size &optional window horizontal pixelwise
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}.  In either case, the optional
argument @var{pixelwise} is passed to the function called.
673 674
@end defun

675
For compatibility with previous versions of Emacs,
676
@code{window-height} is an alias for @code{window-total-height}, and
677 678
@code{window-width} is an alias for @code{window-body-width}.  These
aliases are considered obsolete and will be removed in the future.
679

680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702
   The pixel heights of a window's mode and header line can be retrieved
with the functions given below.  Their return value is usually accurate
unless the window has not been displayed before: In that case, the
return value is based on an estimate of the font used for the window's
frame.

@defun window-mode-line-height &optional window
This function returns the height in pixels of @var{window}'s mode line.
@var{window} must be a live window and defaults to the selected one.  If
@var{window} has no mode line, the return value is zero.
@end defun

@defun window-header-line-height &optional window
This function returns the height in pixels of @var{window}'s header
line.  @var{window} must be a live window and defaults to the selected
one.  If @var{window} has no header line, the return value is zero.
@end defun

Functions for retrieving the height and/or width of window dividers
(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
described in the corresponding sections.

703 704 705 706 707
If your Lisp program needs to make layout decisions, you will find the
following function useful:

@defun window-max-chars-per-line &optional window face
This function returns the number of characters displayed in the
Martin Rudalics's avatar
Martin Rudalics committed
708 709 710 711 712 713 714 715 716 717 718
specified face @var{face} in the specified window @var{window} (which
must be a live window).  If @var{face} was remapped (@pxref{Face
Remapping}), the information is returned for the remapped face.  If
omitted or @code{nil}, @var{face} defaults to the default face, and
@var{window} defaults to the selected window.

Unlike @code{window-body-width}, this function accounts for the actual
size of @var{face}'s font, instead of working in units of the canonical
character width of @var{window}'s frame (@pxref{Frame Font}).  It also
accounts for space used by the continuation glyph, if @var{window} lacks
one or both of its fringes.
719 720
@end defun

721
@cindex fixed-size window
Glenn Morris's avatar
Glenn Morris committed
722 723
@vindex window-min-height
@vindex window-min-width
724 725
  Commands that change the size of windows (@pxref{Resizing Windows}),
or split them (@pxref{Splitting Windows}), obey the variables
726 727 728
@code{window-min-height} and @code{window-min-width}, which specify the
smallest allowable window height and width.  They also obey the variable
@code{window-size-fixed}, with which a window can be @dfn{fixed} in
729
size (@pxref{Preserving Window Sizes}).
730 731 732 733

@defopt window-min-height
This option specifies the minimum total height, in lines, of any window.
Its value has to accommodate at least one text line as well as a mode
734 735
and header line, a horizontal scroll bar and a bottom divider, if
present.
736 737 738 739 740 741 742
@end defopt

@defopt window-min-width
This option specifies the minimum total width, in columns, of any
window.  Its value has to accommodate two text columns as well as
margins, fringes, a scroll bar and a right divider, if present.
@end defopt
743

744 745 746
The following function tells how small a specific window can get taking
into account the sizes of its areas and the values of
@code{window-min-height}, @code{window-min-width} and
Martin Rudalics's avatar
Martin Rudalics committed
747
@code{window-size-fixed} (@pxref{Preserving Window Sizes}).
748 749 750 751 752 753 754 755 756 757

@defun window-min-size &optional window horizontal ignore pixelwise
This function returns the minimum size of @var{window}.  @var{window}
must be a valid window and defaults to the selected one.  The optional
argument @var{horizontal} non-@code{nil} means to return the minimum
number of columns of @var{window}; otherwise return the minimum number
of @var{window}'s lines.

The return value makes sure that all components of @var{window} remain
fully visible if @var{window}'s size were actually set to it.  With
758
@var{horizontal} @code{nil} it includes the mode and header line, the
Martin Rudalics's avatar
Martin Rudalics committed
759 760 761
horizontal scroll bar and the bottom divider, if present.  With
@var{horizontal} non-@code{nil} it includes the margins and fringes, the
vertical scroll bar and the right divider, if present.
762 763 764 765 766 767 768 769 770 771 772 773

The optional argument @var{ignore}, if non-@code{nil}, means ignore
restrictions imposed by fixed size windows, @code{window-min-height} or
@code{window-min-width} settings.  If @var{ignore} equals @code{safe},
live windows may get as small as @code{window-safe-min-height} lines and
@code{window-safe-min-width} columns.  If @var{ignore} is a window,
ignore restrictions for that window only.  Any other non-@code{nil}
value means ignore all of the above restrictions for all windows.

The optional argument @var{pixelwise} non-@code{nil} means to return the
minimum size of @var{window} counted in pixels.
@end defun
774

775

776 777 778 779 780 781 782
@node Resizing Windows
@section Resizing Windows
@cindex window resizing
@cindex resize window
@cindex changing window size
@cindex window size, changing

783 784 785 786 787
  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
788
changed except by resizing the frame (@pxref{Frame Size}).
789 790 791 792

  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.
793

794
@defun window-resizable window delta &optional horizontal ignore pixelwise
795
This function returns @var{delta} if the size of @var{window} can be
796 797 798 799 800 801 802
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
803 804 805 806 807
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.
808 809

Normally, the variables @code{window-min-height} and
810 811 812
@code{window-min-width} specify the smallest allowable window size
(@pxref{Window Sizes}).  However, if the optional argument @var{ignore}
is non-@code{nil}, this function ignores @code{window-min-height} and
813
@code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
814 815 816 817 818
it considers the minimum-height window to be one consisting of a header
and a mode line, a horizontal scrollbar and a bottom divider (if any),
plus a text area one line tall; and a minimum-width window as one
consisting of fringes, margins, a scroll bar and a right divider (if
any), plus a text area two columns wide.
819

820 821
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
822 823
@end defun

824
@defun window-resize window delta &optional horizontal ignore pixelwise
825 826 827 828 829 830 831 832 833 834 835 836
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.

837
If the optional argument @var{pixelwise} is non-@code{nil},
838 839
@var{delta} will be interpreted as pixels.

840
The choice of which window edges this function alters depends on the
841
values of the option @code{window-combination-resize} and the
842
combination limits of the involved windows; in some cases, it may alter
843
both edges.  @xref{Recombining Windows}.  To resize by moving only the
844
bottom or right edge of a window, use the function
845
@code{adjust-window-trailing-edge}.
Glenn Morris's avatar
Glenn Morris committed
846 847
@end defun

848 849 850
@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.
851

852
@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
853
This function moves @var{window}'s bottom edge by @var{delta} lines.
854 855 856
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.
857

858 859
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
860

861 862 863
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
864
moves it as far as possible but does not signal an error.
865 866

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

871 872
@cindex pixelwise, resizing windows
@defopt window-resize-pixelwise
873
If the value of this option is non-@code{nil}, Emacs resizes windows in
874 875 876
units of pixels.  This currently affects functions like
@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
@code{minimize-window}, @code{fit-window-to-buffer},
877 878
@code{fit-frame-to-buffer} and
@code{shrink-window-if-larger-than-buffer} (all listed below).
879

880 881 882
Note that when a frame's pixel size is not a multiple of its character
size, at least one window may get resized pixelwise even if this
option is @code{nil}.  The default value is @code{nil}.
883 884
@end defopt

885 886 887
  The following commands resize windows in more specific ways.  When
called interactively, they act on the selected window.

888
@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905
This command adjusts the height or width 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.

If @var{window} is part of a vertical combination, this function adjusts
@var{window}'s height.  The new height is calculated from the actual
height of the accessible portion of its buffer.  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 non-@code{nil}, specifies the minimum total height
that it can give, which overrides the variable @code{window-min-height}.
Both @var{max-height} and @var{min-height} are specified in lines and
include mode and header line and a bottom divider, if any.

If @var{window} is part of a horizontal combination and the value of the
option @code{fit-window-to-buffer-horizontally} (see below) is
906
non-@code{nil}, this function adjusts @var{window}'s width.  The new
907 908 909 910 911 912 913 914 915
width of @var{window} is calculated from the maximum length of its
buffer's lines that follow the current start position of @var{window}.
The optional argument @var{max-width} specifies a maximum width and
defaults to the width of @var{window}'s frame.  The optional argument
@var{min-width} specifies a minimum width and defaults to
@code{window-min-width}.  Both @var{max-width} and @var{min-width} are
specified in columns and include fringes, margins and scrollbars, if
any.

916 917 918 919
The optional argument @var{preserve-size}, if non-@code{nil}, will
install a parameter to preserve the size of @var{window} during future
resize operations (@pxref{Preserving Window Sizes}).

920 921
If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
this function will try to resize the frame of @var{window} to fit its
922
contents by calling @code{fit-frame-to-buffer} (see below).
923
@end deffn
924

925 926 927 928 929 930 931 932
@defopt fit-window-to-buffer-horizontally
If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
windows horizontally.  If this is @code{nil} (the default)
@code{fit-window-to-buffer} never resizes windows horizontally.  If this
is @code{only}, it can resize windows horizontally only.  Any other
value means @code{fit-window-to-buffer} can resize windows in both
dimensions.
@end defopt
Glenn Morris's avatar
Glenn Morris committed
933

934 935 936 937 938 939 940 941
@defopt fit-frame-to-buffer
If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
frame to its buffer.  A frame is fit if and only if its root window is a
live window and this option is non-@code{nil}.  If this is
@code{horizontally}, frames are fit horizontally only.  If this is
@code{vertically}, frames are fit vertically only.  Any other
non-@code{nil} value means frames can be resized in both dimensions.
@end defopt
942

943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966
If you have a frame that displays only one window, you can fit that
frame to its buffer using the command @code{fit-frame-to-buffer}.

@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
This command adjusts the size of @var{frame} to display the contents of
its buffer exactly.  @var{frame} can be any live frame and defaults to
the selected one.  Fitting is done only if @var{frame}'s root window is
live.  The arguments @var{max-height}, @var{min-height}, @var{max-width}
and @var{min-width} specify bounds on the new total size of
@var{frame}'s root window.  @var{min-height} and @var{min-width} default
to the values of @code{window-min-height} and @code{window-min-width}
respectively.

If the optional argument @var{only} is @code{vertically}, this function
may resize the frame vertically only.  If @var{only} is
@code{horizontally}, it may resize the frame horizontally only.
@end deffn

The behavior of @code{fit-frame-to-buffer} can be controlled with the
help of the two options listed next.

@defopt fit-frame-to-buffer-margins
This option can be used to specify margins around frames to be fit by
@code{fit-frame-to-buffer}.  Such margins can be useful to avoid, for
967 968
example, that the resized frame overlaps the taskbar or parts of its
parent frame.
969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984

It specifies the numbers of pixels to be left free on the left, above,
the right, and below a frame that shall be fit.  The default specifies
@code{nil} for each which means to use no margins.  The value specified
here can be overridden for a specific frame by that frame's
@code{fit-frame-to-buffer-margins} parameter, if present.
@end defopt

@defopt fit-frame-to-buffer-sizes
This option specifies size boundaries for @code{fit-frame-to-buffer}.
It specifies the total maximum and minimum lines and maximum and minimum
columns of the root window of any frame that shall be fit to its buffer.
If any of these values is non-@code{nil}, it overrides the corresponding
argument of @code{fit-frame-to-buffer}.
@end defopt

985
@deffn Command shrink-window-if-larger-than-buffer &optional window
986 987 988 989 990 991 992 993 994 995
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.
996 997 998

This command calls @code{fit-window-to-buffer} (see above) to do its
work.
999 1000
@end deffn

1001

1002 1003 1004 1005 1006
@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
1007 1008
@var{window-or-frame} specifies a window, it balances only that window
and its siblings (@pxref{Windows and Frames}).
1009 1010 1011 1012
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
1013 1014
approximately the same share of the screen area.  Full-width or
full-height windows are not given more space than other windows.
1015 1016 1017 1018
@end deffn

@cindex maximizing windows
@deffn Command maximize-window &optional window
1019 1020 1021 1022
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.
1023 1024 1025 1026
@end deffn

@cindex minimizing windows
@deffn Command minimize-window &optional window
1027 1028 1029 1030
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.
1031 1032 1033
@end deffn


1034 1035 1036 1037 1038 1039 1040 1041
@node Preserving Window Sizes
@section Preserving Window Sizes
@cindex preserving window sizes

A window can get resized explicitly by using one of the functions from
the preceding section or implicitly, for example, when resizing an
adjacent window, when splitting or deleting a window (@pxref{Splitting
Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
1042
(@pxref{Frame Size}).
1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107

  It is possible to avoid implicit resizing of a specific window when
there are one or more other resizable windows on the same frame.  For
this purpose, Emacs must be advised to @dfn{preserve} the size of that
window.  There are two basic ways to do that.

@defvar window-size-fixed
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 the window's size, if there
is no choice.

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.

If this variable is @code{nil}, this does not necessarily mean that any
window showing the buffer can be resized in the desired direction.  To
determine that, use the function @code{window-resizable}.
@xref{Resizing Windows}.
@end defvar

Often @code{window-size-fixed} is overly aggressive because it inhibits
any attempt to explicitly resize or split an affected window as well.
This may even happen after the window has been resized implicitly, for
example, when deleting an adjacent window or resizing the window's
frame.  The following function tries hard to never disallow resizing
such a window explicitly:

@defun window-preserve-size &optional window horizontal preserve
This function (un-)marks the height of window @var{window} as preserved
for future resize operations.  @var{window} must be a live window and
defaults to the selected one.  If the optional argument @var{horizontal}
is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.

If the optional argument @var{preserve} is @code{t}, this means to
preserve the current height/width of @var{window}'s body.  The
height/width of @var{window} will change only if Emacs has no better
choice.  Resizing a window whose height/width is preserved by this
function never throws an error.

If @var{preserve} is @code{nil}, this means to stop preserving the
height/width of @var{window}, lifting any respective restraint induced
by a previous call of this function for @var{window}.  Calling
@code{enlarge-window}, @code{shrink-window} or
@code{fit-window-to-buffer} with @var{window} as argument may also
remove the respective restraint.
@end defun

@code{window-preserve-size} is currently invoked by the following
functions:

@table @code
@item fit-window-to-buffer
If the optional argument @var{preserve-size} of that function
(@pxref{Resizing Windows}) is non-@code{nil}, the size established by
that function is preserved.

@item display-buffer
If the @var{alist} argument of that function (@pxref{Choosing Window})
contains a @code{preserve-size} entry, the size of the window produced
by that function is preserved.
@end table

  @code{window-preserve-size} installs a window parameter (@pxref{Window
1108
Parameters}) called @code{window-preserved-size} which is consulted by the
1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125
window resizing functions.  This parameter will not prevent resizing the
window when the window shows another buffer than the one when
@code{window-preserve-size} was invoked or if its size has changed since
then.

The following function can be used to check whether the height of a
particular window is preserved:

@defun window-preserved-size &optional window horizontal
This function returns the preserved height of window @var{window} in
pixels.  @var{window} must be a live window and defaults to the selected
one.  If the optional argument @var{horizontal} is non-@code{nil}, it
returns the preserved width of @var{window}.  It returns @code{nil} if
the size of @var{window} is not preserved.
@end defun


Glenn Morris's avatar
Glenn Morris committed
1126 1127 1128 1129 1130
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

1131
This section describes functions for creating a new window by
1132 1133 1134 1135
@dfn{splitting} an existing one.  Note that some windows are special in
the sense that these functions may fail to split them as described here.
Examples of such windows are side windows (@pxref{Side Windows}) and
atomic windows (@pxref{Atomic Windows}).
Glenn Morris's avatar
Glenn Morris committed
1136

1137
@defun split-window &optional window size side pixelwise
1138 1139
This function creates a new live window next to the window
@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
Paul Eggert's avatar
Paul Eggert committed
1140
to the selected window.  That window is split, and reduced in
1141 1142
size.  The space is taken up by the new window, which is returned.

1143
The optional second argument @var{size} determines the sizes of
1144 1145 1146 1147 1148 1149 1150 1151
@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
1152 1153 1154
@code{window-min-height} and @code{window-min-width} (@pxref{Window
Sizes}).  Thus, it signals an error if splitting would result in making
a window smaller than those variables specify.  However, a
1155
non-@code{nil} value for @var{size} causes those variables to be
1156 1157
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
1158 1159
wide.

1160 1161 1162 1163 1164
Hence, if @var{size} is specified, it's the caller's responsibility to
check whether the emanating windows are large enough to encompass all
areas like a mode line or a scroll bar.  The function
@code{window-min-size} (@pxref{Window Sizes}) can be used to determine
the minimum requirements of @var{window} in this regard.  Since the new
Paul Eggert's avatar
Paul Eggert committed
1165
window usually inherits areas like the mode line or the scroll bar
1166 1167 1168 1169 1170
from @var{window}, that function is also a good guess for the minimum
size of the new window.  The caller should specify a smaller size only
if it correspondingly removes an inherited area before the next
redisplay.

1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181
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.

1182 1183 1184 1185
The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
to interpret @var{size} in units of pixels, instead of lines and
columns.

1186 1187 1188 1189 1190
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.

1191 1192
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
1193
@code{ignore-window-parameters} is @code{nil}.  If the value of
1194 1195 1196 1197 1198 1199 1200
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}.
1201
@end defun
Glenn Morris's avatar
Glenn Morris committed
1202

1203 1204 1205 1206 1207
  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
1208
@code{(split-window W4)} yields this window configuration:
1209 1210 1211 1212 1213 1214 1215 1216

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
1217 1218
    ||_________________W4_________________||
    | ____________________________________ |
1219 1220 1221 1222 1223 1224 1225 1226 1227
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

1228 1229 1230 1231 1232
@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}.
1233

1234 1235
  Next, we call @code{(split-window W3 nil 'left)}, passing the
internal window @var{W3} as the argument.  The result:
1236 1237 1238 1239 1240

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
1241 1242 1243 1244 1245 1246 1247 1248 1249 1250
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
1251 1252 1253 1254
    |__________________W1__________________|
@end group
@end smallexample

1255
@noindent
1256 1257 1258
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.
1259

1260 1261
   For interactive use, Emacs provides two commands which always split
the selected window.  These call @code{split-window} internally.
1262

1263 1264 1265 1266 1267 1268
@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
1269

1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286
@deffn Command split-window-below &optional size
This function splits the selected window into two windows, one above
the other, leaving the upper window selected.  If @var{size} is
positive, the upper window gets @var{size} lines; if @var{size} is
negative, the lower window gets @minus{}@var{size} lines.
@end deffn

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

If it is @code{nil}, @code{split-window-below} adjusts point in each
of the two windows to minimize redisplay.  (This is useful on slow
terminals.)  It selects whichever window contains the screen line that
point was previously on.  Note that this only affects
@code{split-window-below}, not the lower-level @code{split-window}
function.
Martin Rudalics's avatar
Martin Rudalics committed
1287
@end defopt
1288