windows.texi 187 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-2016 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.
Glenn Morris's avatar
Glenn Morris committed
28
* Choosing Window::         How to choose a window for displaying a buffer.
29 30
* Display Action Functions:: Subroutines for @code{display-buffer}.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
31
* Window History::          Each window remembers the buffers displayed in it.
Glenn Morris's avatar
Glenn Morris committed
32
* Dedicated Windows::       How to avoid displaying another buffer in
33
                              a specific window.
34 35
* Quitting Windows::        How to restore the state prior to displaying a
                              buffer.
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 43
* 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
44
* Window Parameters::       Associating additional information with windows.
Glenn Morris's avatar
Glenn Morris committed
45 46 47 48 49
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
@end menu

50

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

55 56 57
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
58 59

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

67 68
@cindex terminal screen
@cindex screen of terminal
69 70 71 72
  Emacs uses the word ``window'' with a different meaning than in
graphical desktop environments and window systems, such as the X
Window System.  When Emacs is run on X, each of its graphical X
windows is an Emacs frame (containing one or more Emacs windows).
73
When Emacs is run on a text terminal, the frame fills the entire
74
terminal screen.
Glenn Morris's avatar
Glenn Morris committed
75 76

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

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

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

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

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

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

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

136 137 138 139 140 141 142 143
@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.
144 145 146 147 148 149 150 151 152 153 154 155 156 157

@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).
158 159 160 161 162
@end defun

@node Windows and Frames
@section Windows and Frames

163
Each window belongs to exactly one frame (@pxref{Frames}).
164

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

171 172 173 174
@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.
175

176 177 178 179 180 181
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.
182

Martin Rudalics's avatar
Martin Rudalics committed
183 184 185 186
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.
187 188 189
@end defun

@cindex window tree
190 191 192 193 194 195 196 197 198 199 200 201 202 203
@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.
204 205

@defun frame-root-window &optional frame-or-window
206 207 208 209 210
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.
211 212
@end defun

213 214 215 216 217 218 219 220 221 222 223 224
@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}.
225 226 227

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

234 235 236 237 238 239 240 241 242 243
  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.
244 245 246 247

@cindex window combination
@cindex vertical combination
@cindex horizontal combination
248 249 250 251 252 253
  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:
254 255 256 257 258 259

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
260 261 262
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
263 264 265
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
266
    ||      |||                          |||
267 268 269 270 271 272 273
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

@end group
@end smallexample

274
@noindent
275
The root window of this frame is an internal window, @var{W1}.  Its
276
child windows form a horizontal combination, consisting of the live
277 278 279
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
280
window tree are @var{W2}, @var{W4}, and @var{W5}.
281 282 283 284

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

285
@defun window-top-child &optional window
286 287 288 289
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}.
290 291
@end defun

292
@defun window-left-child &optional window
293 294 295 296
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}.
297 298 299
@end defun

@defun window-child window
300 301 302 303
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}.
304 305
@end defun

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

311 312 313
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.
314 315 316
@end defun

@defun window-next-sibling &optional window
317 318 319 320
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.
321 322 323
@end defun

@defun window-prev-sibling &optional window
324 325 326 327
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.
328 329
@end defun

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

336 337
  You can use the following functions to find the first live window on a
frame and the window nearest to a given window.
338 339 340 341 342 343 344 345

@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
346
@code{(frame-first-window)} returns @var{W2}.
347 348
@end defun

349
@cindex window in direction
350
@defun window-in-direction direction &optional window ignore sign wrap mini
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365
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}.

366 367 368 369 370 371 372 373
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
374 375
this function usually returns the frame's minibuffer window if it's
active and a window at the bottom of the frame otherwise.
376 377 378

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
379 380 381
@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}.
382

383 384 385
If it doesn't find a suitable window, this function returns @code{nil}.
@end defun

386 387
The following function allows the entire window tree of a frame to be
retrieved:
388

389
@defun window-tree &optional frame
390 391 392
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.
393 394

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

398 399 400 401 402 403 404 405 406 407
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}).
408 409
@end defun

410

411 412 413 414 415
@node Window Sizes
@section Window Sizes
@cindex window size
@cindex size of window

416
  The following schematic shows the structure of a live window:
417 418 419

@smallexample
@group
420 421
        ____________________________________________
       |______________ Header Line ______________|RD| ^
422
     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
423 424 425 426 427 428
     | |  |  |  |                       |  |  |  |  | |
Window |  |  |  |       Text Area       |  |  |  |  | Window
Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
Height |  |  |  |                       |  |  |  |  | Height
     | |  |  |  |<- Window Body Width ->|  |  |  |  | |
     v |__|__|__|_______________________|__|__|__|  | |
429
       |_________ Horizontal Scroll Bar _________|  | |
430 431 432
       |_______________ Mode Line _______________|__| |
       |_____________ Bottom Divider _______________| v
        <---------- Window Total Width ------------>
433 434 435 436 437

@end group
@end smallexample

@cindex window body
438
@cindex text area of a window
439
@cindex body of a window
440
  At the center of the window is the @dfn{text area}, or @dfn{body},
441 442
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
443 444 445 446 447
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
448
(@pxref{Window Dividers}).  At the top of the window is the header line
449 450 451
(@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}).
452 453 454 455 456

  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
457
width of a default character specified by the frame's default font
458
as returned by @code{frame-char-height} and @code{frame-char-width}
459 460
(@pxref{Frame Font}).  Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
461 462
that window may differ from the actual number of text lines or columns
displayed within it.
463

464 465 466
@cindex window height
@cindex height of a window
@cindex total height of a window
467
  The @dfn{total height} of a window is the number of lines comprising
468 469
the window's body, the header line, the horizontal scroll bar, the mode
line and the bottom divider (if any).
470

471
@defun window-total-height &optional window round
472
This function returns the total height, in lines, of the window
473 474 475 476
@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.

477
  If a window's pixel height is not an integral multiple of its frame's
478 479 480 481 482
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
483 484
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
485 486 487
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})

488
  If the optional argument @var{round} is @code{ceiling}, this
489
function returns the smallest integer larger than @var{window}'s pixel
490 491 492 493
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.
494 495
@end defun

496 497 498 499 500 501 502
@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).

503
@defun window-total-width &optional window round
504
This function returns the total width, in columns, of the window
505 506 507 508
@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.

509
  If a window's pixel width is not an integral multiple of its frame's
510 511 512 513 514 515
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
516
horizontally combined and has a next sibling, the leftmost column of
517
that sibling can be calculated as the sum of this window's leftmost
518 519
column and total width (@pxref{Coordinates and Windows}).  The optional
argument @var{round} behaves as it does for @code{window-total-height}.
520
@end defun
521

522
@defun window-total-size &optional window horizontal round
523 524 525 526 527
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
528
argument @var{round} behaves as it does for @code{window-total-height}.
529 530 531 532 533 534 535 536 537 538 539 540 541
@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.

542 543 544 545
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.
546 547
@end defun

548 549 550
@cindex window pixel width
@cindex pixel width of a window
@cindex total pixel width of a window
551 552 553 554 555 556 557 558 559

@defun window-pixel-width &optional Lisp_Object &optional window
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.
560 561 562
@end defun

@cindex full-width window
563 564 565 566 567
@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
568 569 570 571 572 573
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.
574
@end defun
575 576

@defun window-full-width-p &optional window
577
This function returns non-@code{nil} if @var{window} has no other
578
window to the left or right in its frame, i.e., its total width equals
579 580
that of the root window on that frame.  If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
581 582 583 584
@end defun

@cindex window body height
@cindex body height of a window
585
The @dfn{body height} of a window is the height of its text area, which
586 587
does not include a mode or header line, a horizontal scroll bar, or a
bottom divider.
588

589
@defun window-body-height &optional window pixelwise
590 591 592 593 594 595 596 597 598 599 600 601
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}.
602 603
@end defun

604
@cindex window body width
605 606 607
@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.
608

609 610 611 612 613 614 615 616 617 618 619 620 621
@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}.
622 623
@end defun

624 625
@cindex window body size
@cindex body size of a window
626 627 628 629 630 631
@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.
632 633
@end defun

634
For compatibility with previous versions of Emacs,
635
@code{window-height} is an alias for @code{window-total-height}, and
636 637
@code{window-width} is an alias for @code{window-body-width}.  These
aliases are considered obsolete and will be removed in the future.
638

639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661
   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.

662 663 664 665 666
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
667 668 669 670 671 672 673 674 675 676 677
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.
678 679
@end defun

680
@cindex fixed-size window
Glenn Morris's avatar
Glenn Morris committed
681 682
@vindex window-min-height
@vindex window-min-width
683 684
  Commands that change the size of windows (@pxref{Resizing Windows}),
or split them (@pxref{Splitting Windows}), obey the variables
685 686 687
@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
688
size (@pxref{Preserving Window Sizes}).
689 690 691 692

@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
693 694
and header line, a horizontal scroll bar and a bottom divider, if
present.
695 696 697 698 699 700 701
@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
702

703 704 705
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
706
@code{window-size-fixed} (@pxref{Preserving Window Sizes}).
707 708 709 710 711 712 713 714 715 716

@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
717
@var{horizontal} @code{nil} it includes the mode and header line, the
Martin Rudalics's avatar
Martin Rudalics committed
718 719 720
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.
721 722 723 724 725 726 727 728 729 730 731 732

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
733 734 735 736 737 738 739 740

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

741 742 743 744 745 746 747 748 749 750
  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.
751

752
@defun window-resizable window delta &optional horizontal ignore pixelwise
753
This function returns @var{delta} if the size of @var{window} can be
754 755 756 757 758 759 760
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
761 762 763 764 765
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.
766 767

Normally, the variables @code{window-min-height} and
768 769 770
@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
771
@code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
772 773 774 775 776
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.
777

778 779
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
780 781
@end defun

782
@defun window-resize window delta &optional horizontal ignore pixelwise
783 784 785 786 787 788 789 790 791 792 793 794
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.

795
If the optional argument @var{pixelwise} is non-@code{nil},
796 797
@var{delta} will be interpreted as pixels.

798
The choice of which window edges this function alters depends on the
799
values of the option @code{window-combination-resize} and the
800
combination limits of the involved windows; in some cases, it may alter
801
both edges.  @xref{Recombining Windows}.  To resize by moving only the
802
bottom or right edge of a window, use the function
803
@code{adjust-window-trailing-edge}.
Glenn Morris's avatar
Glenn Morris committed
804 805
@end defun

806 807 808
@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.
809

810
@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
811
This function moves @var{window}'s bottom edge by @var{delta} lines.
812 813 814
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.
815

816 817
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
818

819 820 821 822
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.
823 824

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

829 830
@cindex pixelwise, resizing windows
@defopt window-resize-pixelwise
831
If the value of this option is non-@code{nil}, Emacs resizes windows in
832 833 834
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},
835 836
@code{fit-frame-to-buffer} and
@code{shrink-window-if-larger-than-buffer} (all listed below).
837

838 839 840
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}.
841 842
@end defopt

843 844 845
  The following commands resize windows in more specific ways.  When
called interactively, they act on the selected window.

846
@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873
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
non-@code{nil}, this function adjusts @var{window}'s height.  The new
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.

874 875 876 877
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}).

878 879
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
880
contents by calling @code{fit-frame-to-buffer} (see below).
881
@end deffn
882

883 884 885 886 887 888 889 890
@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
891

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

901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941
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
example, that such frames overlap the taskbar.

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

942
@deffn Command shrink-window-if-larger-than-buffer &optional window
943 944 945 946 947 948 949 950 951 952
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.
953 954 955

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

958

959 960 961 962 963
@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
964 965
@var{window-or-frame} specifies a window, it balances only that window
and its siblings (@pxref{Windows and Frames}).
966 967 968 969
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame
970 971
approximately the same share of the screen area.  Full-width or
full-height windows are not given more space than other windows.
972 973 974 975
@end deffn

@cindex maximizing windows
@deffn Command maximize-window &optional window
976 977 978 979
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.
980 981 982 983
@end deffn

@cindex minimizing windows
@deffn Command minimize-window &optional window
984 985 986 987
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.
988 989 990
@end deffn


991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082
@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
(@pxref{Size and Position}).

  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
Parameters}) called @code{preserved-size} which is consulted by the
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
1083 1084 1085 1086 1087
@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

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

1091
@defun split-window &optional window size side pixelwise
1092 1093
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
1094
to the selected window.  That window is split, and reduced in
1095 1096
size.  The space is taken up by the new window, which is returned.

1097
The optional second argument @var{size} determines the sizes of
1098 1099 1100 1101 1102 1103 1104 1105
@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
1106 1107 1108
@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
1109
non-@code{nil} value for @var{size} causes those variables to be
1110 1111
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
1112 1113
wide.

1114 1115 1116 1117 1118
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
1119
window usually inherits areas like the mode line or the scroll bar
1120 1121 1122 1123 1124
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.

1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135
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.

1136 1137 1138 1139
The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
to interpret @var{size} in units of pixels, instead of lines and
columns.

1140 1141 1142 1143 1144
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.

1145 1146
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
1147
@code{ignore-window-parameters} is @code{nil}.  If the value of
1148 1149 1150 1151 1152 1153 1154
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}.
1155
@end defun
Glenn Morris's avatar
Glenn Morris committed
1156

1157 1158 1159 1160 1161
  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
1162
@code{(split-window W4)} yields this window configuration:
1163 1164 1165 1166 1167 1168 1169 1170

@smallexample
@group
     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
1171 1172
    ||_________________W4_________________||
    | ____________________________________ |
1173 1174 1175 1176 1177 1178 1179 1180 1181
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

@end group
@end smallexample

1182 1183 1184 1185 1186
@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}.
1187

1188 1189
  Next, we call @code{(split-window W3 nil 'left)}, passing the
internal window @var{W3} as the argument.  The result:
1190 1191 1192 1193 1194

@smallexample
@group
     ______________________________________
    | ______  ____________________________ |
1195 1196 1197 1198 1199 1200 1201 1202 1203 1204
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |