1@c -*-texinfo-*- 2@c This is part of the GNU Emacs Lisp Reference Manual. 3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 4@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5@c See the file elisp.texi for copying conditions. 6@setfilename ../info/windows 7@node Windows, Frames, Buffers, Top 8@chapter Windows 9 10 This chapter describes most of the functions and variables related to 11Emacs windows. See @ref{Display}, for information on how text is 12displayed in windows. 13 14@menu 15* Basic Windows:: Basic information on using windows. 16* Splitting Windows:: Splitting one window into two windows. 17* Deleting Windows:: Deleting a window gives its space to other windows. 18* Selecting Windows:: The selected window is the one that you edit in. 19* Cyclic Window Ordering:: Moving around the existing windows. 20* Buffers and Windows:: Each window displays the contents of a buffer. 21* Displaying Buffers:: Higher-level functions for displaying a buffer 22 and choosing a window for it. 23* Choosing Window:: How to choose a window for displaying a buffer. 24* Window Point:: Each window has its own location of point. 25* Window Start:: The display-start position controls which text 26 is on-screen in the window. 27* Textual Scrolling:: Moving text up and down through the window. 28* Vertical Scrolling:: Moving the contents up and down on the window. 29* Horizontal Scrolling:: Moving the contents sideways on the window. 30* Size of Window:: Accessing the size of a window. 31* Resizing Windows:: Changing the size of a window. 32* Coordinates and Windows:: Converting coordinates to windows. 33* Window Tree:: The layout and sizes of all windows in a frame. 34* Window Configurations:: Saving and restoring the state of the screen. 35* Window Hooks:: Hooks for scrolling, window size changes, 36 redisplay going past a certain point, 37 or window configuration changes. 38@end menu 39 40@node Basic Windows 41@section Basic Concepts of Emacs Windows 42@cindex window 43@cindex selected window 44 45 A @dfn{window} in Emacs is the physical area of the screen in which a 46buffer is displayed. The term is also used to refer to a Lisp object that 47represents that screen area in Emacs Lisp. It should be 48clear from the context which is meant. 49 50 Emacs groups windows into frames. A frame represents an area of 51screen available for Emacs to use. Each frame always contains at least 52one window, but you can subdivide it vertically or horizontally into 53multiple nonoverlapping Emacs windows. 54 55 In each frame, at any time, one and only one window is designated as 56@dfn{selected within the frame}. The frame's cursor appears in that 57window, but the other windows have ``non-selected'' cursors, normally 58less visible. At any time, one frame is the selected frame; and the 59window selected within that frame is @dfn{the selected window}. The 60selected window's buffer is usually the current buffer (except when 61@code{set-buffer} has been used). @xref{Current Buffer}. 62 63@defvar cursor-in-non-selected-windows 64If this variable is @code{nil}, Emacs displays only one cursor, 65in the selected window. Other windows have no cursor at all. 66@end defvar 67 68 For practical purposes, a window exists only while it is displayed in 69a frame. Once removed from the frame, the window is effectively deleted 70and should not be used, @emph{even though there may still be references 71to it} from other Lisp objects. Restoring a saved window configuration 72is the only way for a window no longer on the screen to come back to 73life. (@xref{Deleting Windows}.) 74 75 Each window has the following attributes: 76 77@itemize @bullet 78@item 79containing frame 80 81@item 82window height 83 84@item 85window width 86 87@item 88window edges with respect to the screen or frame 89 90@item 91the buffer it displays 92 93@item 94position within the buffer at the upper left of the window 95 96@item 97amount of horizontal scrolling, in columns 98 99@item 100point 101 102@item 103the mark 104 105@item 106how recently the window was selected 107 108@item 109fringe settings 110 111@item 112display margins 113 114@item 115scroll-bar settings 116@end itemize 117 118@cindex multiple windows 119 Users create multiple windows so they can look at several buffers at 120once. Lisp libraries use multiple windows for a variety of reasons, but 121most often to display related information. In Rmail, for example, you 122can move through a summary buffer in one window while the other window 123shows messages one at a time as they are reached. 124 125 The meaning of ``window'' in Emacs is similar to what it means in the 126context of general-purpose window systems such as X, but not identical. 127The X Window System places X windows on the screen; Emacs uses one or 128more X windows as frames, and subdivides them into 129Emacs windows. When you use Emacs on a character-only terminal, Emacs 130treats the whole terminal screen as one frame. 131 132@cindex terminal screen 133@cindex screen of terminal 134@cindex tiled windows 135 Most window systems support arbitrarily located overlapping windows. 136In contrast, Emacs windows are @dfn{tiled}; they never overlap, and 137together they fill the whole screen or frame. Because of the way in 138which Emacs creates new windows and resizes them, not all conceivable 139tilings of windows on an Emacs frame are actually possible. 140@xref{Splitting Windows}, and @ref{Size of Window}. 141 142 @xref{Display}, for information on how the contents of the 143window's buffer are displayed in the window. 144 145@defun windowp object 146This function returns @code{t} if @var{object} is a window. 147@end defun 148 149@node Splitting Windows 150@section Splitting Windows 151@cindex splitting windows 152@cindex window splitting 153 154 The functions described here are the primitives used to split a window 155into two windows. Two higher level functions sometimes split a window, 156but not always: @code{pop-to-buffer} and @code{display-buffer} 157(@pxref{Displaying Buffers}). 158 159 The functions described here do not accept a buffer as an argument. 160The two ``halves'' of the split window initially display the same buffer 161previously visible in the window that was split. 162 163@deffn Command split-window &optional window size horizontal 164This function splits a new window out of @var{window}'s screen area. 165It returns the new window. 166 167If @var{horizontal} is non-@code{nil}, then @var{window} splits into 168two side by side windows. The original window @var{window} keeps the 169leftmost @var{size} columns, and gives the rest of the columns to the 170new window. Otherwise, it splits into windows one above the other, and 171@var{window} keeps the upper @var{size} lines and gives the rest of the 172lines to the new window. The original window is therefore the 173left-hand or upper of the two, and the new window is the right-hand or 174lower. 175 176If @var{window} is omitted or @code{nil}, that stands for the selected 177window. When you split the selected window, it remains selected. 178 179If @var{size} is omitted or @code{nil}, then @var{window} is divided 180evenly into two parts. (If there is an odd line, it is allocated to 181the new window.) When @code{split-window} is called interactively, 182all its arguments are @code{nil}. 183 184If splitting would result in making a window that is smaller than 185@code{window-min-height} or @code{window-min-width}, the function 186signals an error and does not split the window at all. 187 188The following example starts with one window on a screen that is 50 189lines high by 80 columns wide; then it splits the window. 190 191@smallexample 192@group 193(setq w (selected-window)) 194 @result{} #<window 8 on windows.texi> 195(window-edges) ; @r{Edges in order:} 196 @result{} (0 0 80 50) ; @r{left--top--right--bottom} 197@end group 198 199@group 200;; @r{Returns window created} 201(setq w2 (split-window w 15)) 202 @result{} #<window 28 on windows.texi> 203@end group 204@group 205(window-edges w2) 206 @result{} (0 15 80 50) ; @r{Bottom window;} 207 ; @r{top is line 15} 208@end group 209@group 210(window-edges w) 211 @result{} (0 0 80 15) ; @r{Top window} 212@end group 213@end smallexample 214 215The screen looks like this: 216 217@smallexample 218@group 219 __________ 220 | | line 0 221 | w | 222 |__________| 223 | | line 15 224 | w2 | 225 |__________| 226 line 50 227 column 0 column 80 228@end group 229@end smallexample 230 231Next, split the top window horizontally: 232 233@smallexample 234@group 235(setq w3 (split-window w 35 t)) 236 @result{} #<window 32 on windows.texi> 237@end group 238@group 239(window-edges w3) 240 @result{} (35 0 80 15) ; @r{Left edge at column 35} 241@end group 242@group 243(window-edges w) 244 @result{} (0 0 35 15) ; @r{Right edge at column 35} 245@end group 246@group 247(window-edges w2) 248 @result{} (0 15 80 50) ; @r{Bottom window unchanged} 249@end group 250@end smallexample 251 252@need 3000 253Now the screen looks like this: 254 255@smallexample 256@group 257 column 35 258 __________ 259 | | | line 0 260 | w | w3 | 261 |___|______| 262 | | line 15 263 | w2 | 264 |__________| 265 line 50 266 column 0 column 80 267@end group 268@end smallexample 269 270Normally, Emacs indicates the border between two side-by-side windows 271with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|} 272characters. The display table can specify alternative border 273characters; see @ref{Display Tables}. 274@end deffn 275 276@deffn Command split-window-vertically &optional size 277This function splits the selected window into two windows, one above the 278other, leaving the upper of the two windows selected, with @var{size} 279lines. (If @var{size} is negative, then the lower of the two windows 280gets @minus{} @var{size} lines and the upper window gets the rest, but 281the upper window is still the one selected.) However, if 282@code{split-window-keep-point} (see below) is @code{nil}, then either 283window can be selected. 284 285In other respects, this function is similar to @code{split-window}. 286In particular, the upper window is the original one and the return 287value is the new, lower window. 288@end deffn 289 290@defopt split-window-keep-point 291If this variable is non-@code{nil} (the default), then 292@code{split-window-vertically} behaves as described above. 293 294If it is @code{nil}, then @code{split-window-vertically} adjusts point 295in each of the two windows to avoid scrolling. (This is useful on 296slow terminals.) It selects whichever window contains the screen line 297that point was previously on. 298 299This variable only affects the behavior of @code{split-window-vertically}. 300It has no effect on the other functions described here. 301@end defopt 302 303@deffn Command split-window-horizontally &optional size 304This function splits the selected window into two windows 305side-by-side, leaving the selected window on the left with @var{size} 306columns. If @var{size} is negative, the rightmost window gets 307@minus{} @var{size} columns, but the leftmost window still remains 308selected. 309 310This function is basically an interface to @code{split-window}. 311You could define a simplified version of the function like this: 312 313@smallexample 314@group 315(defun split-window-horizontally (&optional arg) 316 "Split selected window into two windows, side by side..." 317 (interactive "P") 318@end group 319@group 320 (let ((size (and arg (prefix-numeric-value arg)))) 321 (and size (< size 0) 322 (setq size (+ (window-width) size))) 323 (split-window nil size t))) 324@end group 325@end smallexample 326@end deffn 327 328@defun one-window-p &optional no-mini all-frames 329This function returns non-@code{nil} if there is only one window. The 330argument @var{no-mini}, if non-@code{nil}, means don't count the 331minibuffer even if it is active; otherwise, the minibuffer window is 332counted when it is active. 333 334The argument @var{all-frames} specifies which frames to consider. Here 335are the possible values and their meanings: 336 337@table @asis 338@item @code{nil} 339Count the windows in the selected frame, plus the minibuffer used 340by that frame even if it lies in some other frame. 341 342@item @code{t} 343Count all windows in all existing frames. 344 345@item @code{visible} 346Count all windows in all visible frames. 347 348@item 0 349Count all windows in all visible or iconified frames. 350 351@item anything else 352Count precisely the windows in the selected frame, and no others. 353@end table 354@end defun 355 356@node Deleting Windows 357@section Deleting Windows 358@cindex deleting windows 359 360A window remains visible on its frame unless you @dfn{delete} it by 361calling certain functions that delete windows. A deleted window cannot 362appear on the screen, but continues to exist as a Lisp object until 363there are no references to it. There is no way to cancel the deletion 364of a window aside from restoring a saved window configuration 365(@pxref{Window Configurations}). Restoring a window configuration also 366deletes any windows that aren't part of that configuration. 367 368 When you delete a window, the space it took up is given to one 369adjacent sibling. 370 371@c Emacs 19 feature 372@defun window-live-p window 373This function returns @code{nil} if @var{window} is deleted, and 374@code{t} otherwise. 375 376@strong{Warning:} Erroneous information or fatal errors may result from 377using a deleted window as if it were live. 378@end defun 379 380@deffn Command delete-window &optional window 381This function removes @var{window} from display, and returns @code{nil}. 382If @var{window} is omitted, then the selected window is deleted. An 383error is signaled if there is only one window when @code{delete-window} 384is called. 385@end deffn 386 387@deffn Command delete-other-windows &optional window 388This function makes @var{window} the only window on its frame, by 389deleting the other windows in that frame. If @var{window} is omitted or 390@code{nil}, then the selected window is used by default. 391 392The return value is @code{nil}. 393@end deffn 394 395@deffn Command delete-windows-on buffer-or-name &optional frame 396This function deletes all windows showing @var{buffer-or-name}. If 397there are no windows showing @var{buffer-or-name}, it does nothing. 398@var{buffer-or-name} must be a buffer or the name of an existing 399buffer. 400 401@code{delete-windows-on} operates frame by frame. If a frame has 402several windows showing different buffers, then those showing 403@var{buffer-or-name} are removed, and the others expand to fill the 404space. If all windows in some frame are showing @var{buffer-or-name} 405(including the case where there is only one window), then the frame 406winds up with a single window showing another buffer chosen with 407@code{other-buffer}. @xref{The Buffer List}. 408 409The argument @var{frame} controls which frames to operate on. This 410function does not use it in quite the same way as the other functions 411which scan all windows; specifically, the values @code{t} and @code{nil} 412have the opposite of their meanings in other functions. Here are the 413full details: 414 415@itemize @bullet 416@item 417If it is @code{nil}, operate on all frames. 418@item 419If it is @code{t}, operate on the selected frame. 420@item 421If it is @code{visible}, operate on all visible frames. 422@item 423If it is 0, operate on all visible or iconified frames. 424@item 425If it is a frame, operate on that frame. 426@end itemize 427 428This function always returns @code{nil}. 429@end deffn 430 431@node Selecting Windows 432@section Selecting Windows 433@cindex selecting a window 434 435 When a window is selected, the buffer in the window becomes the current 436buffer, and the cursor will appear in it. 437 438@defun selected-window 439This function returns the selected window. This is the window in 440which the cursor appears and to which many commands apply. 441@end defun 442 443@defun select-window window &optional norecord 444This function makes @var{window} the selected window. The cursor then 445appears in @var{window} (on redisplay). Unless @var{window} was 446already selected, @code{select-window} makes @var{window}'s buffer the 447current buffer. 448 449Normally @var{window}'s selected buffer is moved to the front of the 450buffer list, but if @var{norecord} is non-@code{nil}, the buffer list 451order is unchanged. 452 453The return value is @var{window}. 454 455@example 456@group 457(setq w (next-window)) 458(select-window w) 459 @result{} #<window 65 on windows.texi> 460@end group 461@end example 462@end defun 463 464@defmac save-selected-window forms@dots{} 465This macro records the selected frame, as well as the selected window 466of each frame, executes @var{forms} in sequence, then restores the 467earlier selected frame and windows. It also saves and restores the 468current buffer. It returns the value of the last form in @var{forms}. 469 470This macro does not save or restore anything about the sizes, 471arrangement or contents of windows; therefore, if the @var{forms} 472change them, the change persists. If the previously selected window 473of some frame is no longer live at the time of exit from @var{forms}, 474that frame's selected window is left alone. If the previously 475selected window is no longer live, then whatever window is selected at 476the end of @var{forms} remains selected. 477@end defmac 478 479@defmac with-selected-window window forms@dots{} 480This macro selects @var{window} (without changing the buffer list), 481executes @var{forms} in sequence, then restores the previously 482selected window and current buffer. It is just like 483@code{save-selected-window}, except that it explicitly selects 484@var{window}, also without altering the buffer list sequence. 485@end defmac 486 487@cindex finding windows 488 The following functions choose one of the windows on the screen, 489offering various criteria for the choice. 490 491@defun get-lru-window &optional frame dedicated 492This function returns the window least recently ``used'' (that is, 493selected). If any full-width windows are present, it only considers 494these. The selected window is always the most recently used window. 495 496The selected window can be the least recently used window if it is the 497only window. A newly created window becomes the least recently used 498window until it is selected. A minibuffer window is never a 499candidate. Dedicated windows are never candidates unless the 500@var{dedicated} argument is non-@code{nil}, so if all 501existing windows are dedicated, the value is @code{nil}. 502 503The argument @var{frame} controls which windows are considered. 504 505@itemize @bullet 506@item 507If it is @code{nil}, consider windows on the selected frame. 508@item 509If it is @code{t}, consider windows on all frames. 510@item 511If it is @code{visible}, consider windows on all visible frames. 512@item 513If it is 0, consider windows on all visible or iconified frames. 514@item 515If it is a frame, consider windows on that frame. 516@end itemize 517@end defun 518 519@defun get-largest-window &optional frame dedicated 520This function returns the window with the largest area (height times 521width). If there are no side-by-side windows, then this is the window 522with the most lines. A minibuffer window is never a candidate. 523Dedicated windows are never candidates unless the 524@var{dedicated} argument is non-@code{nil}, so if all existing windows 525are dedicated, the value is @code{nil}. 526 527If there are two candidate windows of the same size, this function 528prefers the one that comes first in the cyclic ordering of windows 529(see following section), starting from the selected window. 530 531The argument @var{frame} controls which set of windows to 532consider. See @code{get-lru-window}, above. 533@end defun 534 535@cindex window that satisfies a predicate 536@cindex conditional selection of windows 537@defun get-window-with-predicate predicate &optional minibuf all-frames default 538This function returns a window satisfying @var{predicate}. It cycles 539through all visible windows using @code{walk-windows} (@pxref{Cyclic 540Window Ordering}), calling @var{predicate} on each one of them 541with that window as its argument. The function returns the first 542window for which @var{predicate} returns a non-@code{nil} value; if 543that never happens, it returns @var{default}. 544 545The optional arguments @var{minibuf} and @var{all-frames} specify the 546set of windows to include in the scan. See the description of 547@code{next-window} in @ref{Cyclic Window Ordering}, for details. 548@end defun 549 550@node Cyclic Window Ordering 551@comment node-name, next, previous, up 552@section Cyclic Ordering of Windows 553@cindex cyclic ordering of windows 554@cindex ordering of windows, cyclic 555@cindex window ordering, cyclic 556 557 When you use the command @kbd{C-x o} (@code{other-window}) to select 558the next window, it moves through all the windows on the screen in a 559specific cyclic order. For any given configuration of windows, this 560order never varies. It is called the @dfn{cyclic ordering of windows}. 561 562 This ordering generally goes from top to bottom, and from left to 563right. But it may go down first or go right first, depending on the 564order in which the windows were split. 565 566 If the first split was vertical (into windows one above each other), 567and then the subwindows were split horizontally, then the ordering is 568left to right in the top of the frame, and then left to right in the 569next lower part of the frame, and so on. If the first split was 570horizontal, the ordering is top to bottom in the left part, and so on. 571In general, within each set of siblings at any level in the window tree, 572the order is left to right, or top to bottom. 573 574@defun next-window &optional window minibuf all-frames 575@cindex minibuffer window, and @code{next-window} 576This function returns the window following @var{window} in the cyclic 577ordering of windows. This is the window that @kbd{C-x o} would select 578if typed when @var{window} is selected. If @var{window} is the only 579window visible, then this function returns @var{window}. If omitted, 580@var{window} defaults to the selected window. 581 582The value of the argument @var{minibuf} determines whether the 583minibuffer is included in the window order. Normally, when 584@var{minibuf} is @code{nil}, the minibuffer is included if it is 585currently active; this is the behavior of @kbd{C-x o}. (The minibuffer 586window is active while the minibuffer is in use. @xref{Minibuffers}.) 587 588If @var{minibuf} is @code{t}, then the cyclic ordering includes the 589minibuffer window even if it is not active. 590 591If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer 592window is not included even if it is active. 593 594The argument @var{all-frames} specifies which frames to consider. Here 595are the possible values and their meanings: 596 597@table @asis 598@item @code{nil} 599Consider all the windows in @var{window}'s frame, plus the minibuffer 600used by that frame even if it lies in some other frame. If the 601minibuffer counts (as determined by @var{minibuf}), then all windows on 602all frames that share that minibuffer count too. 603 604@item @code{t} 605Consider all windows in all existing frames. 606 607@item @code{visible} 608Consider all windows in all visible frames. (To get useful results, you 609must ensure @var{window} is in a visible frame.) 610 611@item 0 612Consider all windows in all visible or iconified frames. 613 614@item a frame 615Consider all windows on that frame. 616 617@item anything else 618Consider precisely the windows in @var{window}'s frame, and no others. 619@end table 620 621This example assumes there are two windows, both displaying the 622buffer @samp{windows.texi}: 623 624@example 625@group 626(selected-window) 627 @result{} #<window 56 on windows.texi> 628@end group 629@group 630(next-window (selected-window)) 631 @result{} #<window 52 on windows.texi> 632@end group 633@group 634(next-window (next-window (selected-window))) 635 @result{} #<window 56 on windows.texi> 636@end group 637@end example 638@end defun 639 640@defun previous-window &optional window minibuf all-frames 641This function returns the window preceding @var{window} in the cyclic 642ordering of windows. The other arguments specify which windows to 643include in the cycle, as in @code{next-window}. 644@end defun 645 646@deffn Command other-window count &optional all-frames 647This function selects the @var{count}th following window in the cyclic 648order. If count is negative, then it moves back @minus{}@var{count} 649windows in the cycle, rather than forward. It returns @code{nil}. 650 651The argument @var{all-frames} has the same meaning as in 652@code{next-window}, but the @var{minibuf} argument of @code{next-window} 653is always effectively @code{nil}. 654 655In an interactive call, @var{count} is the numeric prefix argument. 656@end deffn 657 658@c Emacs 19 feature 659@defun walk-windows proc &optional minibuf all-frames 660This function cycles through all windows. It calls the function 661@code{proc} once for each window, with the window as its sole 662argument. 663 664The optional arguments @var{minibuf} and @var{all-frames} specify the 665set of windows to include in the scan. See @code{next-window}, above, 666for details. 667@end defun 668 669@defun window-list &optional frame minibuf window 670This function returns a list of the windows on @var{frame}, starting 671with @var{window}. If @var{frame} is @code{nil} or omitted, 672@code{window-list} uses the selected frame instead; if @var{window} is 673@code{nil} or omitted, it uses the selected window. 674 675The value of @var{minibuf} determines if the minibuffer window is 676included in the result list. If @var{minibuf} is @code{t}, the result 677always includes the minibuffer window. If @var{minibuf} is @code{nil} 678or omitted, that includes the minibuffer window if it is active. If 679@var{minibuf} is neither @code{nil} nor @code{t}, the result never 680includes the minibuffer window. 681@end defun 682 683@node Buffers and Windows 684@section Buffers and Windows 685@cindex examining windows 686@cindex windows, controlling precisely 687@cindex buffers, controlled in windows 688 689 This section describes low-level functions to examine windows or to 690display buffers in windows in a precisely controlled fashion. 691@iftex 692See the following section for 693@end iftex 694@ifnottex 695@xref{Displaying Buffers}, for 696@end ifnottex 697related functions that find a window to use and specify a buffer for it. 698The functions described there are easier to use than these, but they 699employ heuristics in choosing or creating a window; use these functions 700when you need complete control. 701 702@defun set-window-buffer window buffer-or-name &optional keep-margins 703This function makes @var{window} display @var{buffer-or-name} as its 704contents. It returns @code{nil}. @var{buffer-or-name} must be a 705buffer, or the name of an existing buffer. This is the fundamental 706primitive for changing which buffer is displayed in a window, and all 707ways of doing that call this function. 708 709@example 710@group 711(set-window-buffer (selected-window) "foo") 712 @result{} nil 713@end group 714@end example 715 716Normally, displaying @var{buffer} in @var{window} resets the window's 717display margins, fringe widths, scroll bar settings, and position 718based on the local variables of @var{buffer}. However, if 719@var{keep-margins} is non-@code{nil}, the display margins and fringe 720widths of @var{window} remain unchanged. @xref{Fringes}. 721@end defun 722 723@defvar buffer-display-count 724This buffer-local variable records the number of times a buffer is 725displayed in a window. It is incremented each time 726@code{set-window-buffer} is called for the buffer. 727@end defvar 728 729@defun window-buffer &optional window 730This function returns the buffer that @var{window} is displaying. If 731@var{window} is omitted, this function returns the buffer for the 732selected window. 733 734@example 735@group 736(window-buffer) 737 @result{} #<buffer windows.texi> 738@end group 739@end example 740@end defun 741 742@defun get-buffer-window buffer-or-name &optional all-frames 743This function returns a window currently displaying 744@var{buffer-or-name}, or @code{nil} if there is none. If there are 745several such windows, then the function returns the first one in the 746cyclic ordering of windows, starting from the selected window. 747@xref{Cyclic Window Ordering}. 748 749The argument @var{all-frames} controls which windows to consider. 750 751@itemize @bullet 752@item 753If it is @code{nil}, consider windows on the selected frame. 754@item 755If it is @code{t}, consider windows on all frames. 756@item 757If it is @code{visible}, consider windows on all visible frames. 758@item 759If it is 0, consider windows on all visible or iconified frames. 760@item 761If it is a frame, consider windows on that frame. 762@end itemize 763@end defun 764 765@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames 766This function returns a list of all the windows currently displaying 767@var{buffer-or-name}. 768 769The two optional arguments work like the optional arguments of 770@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} 771like the single optional argument of @code{get-buffer-window}. Perhaps 772we should change @code{get-buffer-window} in the future to make it 773compatible with the other functions. 774@end defun 775 776@defvar buffer-display-time 777This variable records the time at which a buffer was last made visible 778in a window. It is always local in each buffer; each time 779@code{set-window-buffer} is called, it sets this variable to 780@code{(current-time)} in the specified buffer (@pxref{Time of Day}). 781When a buffer is first created, @code{buffer-display-time} starts out 782with the value @code{nil}. 783@end defvar 784 785@node Displaying Buffers 786@section Displaying Buffers in Windows 787@cindex switching to a buffer 788@cindex displaying a buffer 789 790 In this section we describe convenient functions that choose a window 791automatically and use it to display a specified buffer. These functions 792can also split an existing window in certain circumstances. We also 793describe variables that parameterize the heuristics used for choosing a 794window. 795@iftex 796See the preceding section for 797@end iftex 798@ifnottex 799@xref{Buffers and Windows}, for 800@end ifnottex 801low-level functions that give you more precise control. All of these 802functions work by calling @code{set-window-buffer}. 803 804 Do not use the functions in this section in order to make a buffer 805current so that a Lisp program can access or modify it; they are too 806drastic for that purpose, since they change the display of buffers in 807windows, which would be gratuitous and surprise the user. Instead, use 808@code{set-buffer} and @code{save-current-buffer} (@pxref{Current 809Buffer}), which designate buffers as current for programmed access 810without affecting the display of buffers in windows. 811 812@deffn Command switch-to-buffer buffer-or-name &optional norecord 813This function makes @var{buffer-or-name} the current buffer, and also 814displays the buffer in the selected window. This means that a human can 815see the buffer and subsequent keyboard commands will apply to it. 816Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} 817the current buffer but does not display it in the selected window. 818@xref{Current Buffer}. 819 820If @var{buffer-or-name} does not identify an existing buffer, then a new 821buffer by that name is created. The major mode for the new buffer is 822set according to the variable @code{default-major-mode}. @xref{Auto 823Major Mode}. If @var{buffer-or-name} is @code{nil}, 824@code{switch-to-buffer} chooses a buffer using @code{other-buffer}. 825 826Normally the specified buffer is put at the front of the buffer list 827(both the selected frame's buffer list and the frame-independent buffer 828list). This affects the operation of @code{other-buffer}. However, if 829@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer 830List}. 831 832The @code{switch-to-buffer} function is often used interactively, as 833the binding of @kbd{C-x b}. It is also used frequently in programs. It 834returns the buffer that it switched to. 835@end deffn 836 837The next two functions are similar to @code{switch-to-buffer}, except 838for the described features. 839 840@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord 841This function makes @var{buffer-or-name} the current buffer and 842displays it in a window not currently selected. It then selects that 843window. The handling of the buffer is the same as in 844@code{switch-to-buffer}. 845 846The currently selected window is absolutely never used to do the job. 847If it is the only window, then it is split to make a distinct window for 848this purpose. If the selected window is already displaying the buffer, 849then it continues to do so, but another window is nonetheless found to 850display it in as well. 851 852This function updates the buffer list just like @code{switch-to-buffer} 853unless @var{norecord} is non-@code{nil}. 854@end deffn 855 856@defun pop-to-buffer buffer-or-name &optional other-window norecord 857This function makes @var{buffer-or-name} the current buffer and 858switches to it in some window, preferably not the window previously 859selected. The ``popped-to'' window becomes the selected window within 860its frame. The return value is the buffer that was switched to. 861If @var{buffer-or-name} is @code{nil}, that means to choose some 862other buffer, but you don't specify which. 863 864If the variable @code{pop-up-frames} is non-@code{nil}, 865@code{pop-to-buffer} looks for a window in any visible frame already 866displaying the buffer; if there is one, it returns that window and makes 867it be selected within its frame. If there is none, it creates a new 868frame and displays the buffer in it. 869 870If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer} 871operates entirely within the selected frame. (If the selected frame has 872just a minibuffer, @code{pop-to-buffer} operates within the most 873recently selected frame that was not just a minibuffer.) 874 875If the variable @code{pop-up-windows} is non-@code{nil}, windows may 876be split to create a new window that is different from the original 877window. For details, see @ref{Choosing Window}. 878 879If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or 880creates another window even if @var{buffer-or-name} is already visible 881in the selected window. Thus @var{buffer-or-name} could end up 882displayed in two windows. On the other hand, if @var{buffer-or-name} is 883already displayed in the selected window and @var{other-window} is 884@code{nil}, then the selected window is considered sufficient display 885for @var{buffer-or-name}, so that nothing needs to be done. 886 887All the variables that affect @code{display-buffer} affect 888@code{pop-to-buffer} as well. @xref{Choosing Window}. 889 890If @var{buffer-or-name} is a string that does not name an existing 891buffer, a buffer by that name is created. The major mode for the new 892buffer is set according to the variable @code{default-major-mode}. 893@xref{Auto Major Mode}. 894 895This function updates the buffer list just like @code{switch-to-buffer} 896unless @var{norecord} is non-@code{nil}. 897@end defun 898 899@deffn Command replace-buffer-in-windows buffer-or-name 900This function replaces @var{buffer-or-name} with some other buffer in all 901windows displaying it. It chooses the other buffer with 902@code{other-buffer}. In the usual applications of this function, you 903don't care which other buffer is used; you just want to make sure that 904@var{buffer-or-name} is no longer displayed. 905 906This function returns @code{nil}. 907@end deffn 908 909@node Choosing Window 910@section Choosing a Window for Display 911 912 This section describes the basic facility that chooses a window to 913display a buffer in---@code{display-buffer}. All the higher-level 914functions and commands use this subroutine. Here we describe how to use 915@code{display-buffer} and how to customize it. 916 917@deffn Command display-buffer buffer-or-name &optional not-this-window frame 918This command makes @var{buffer-or-name} appear in some window, like 919@code{pop-to-buffer}, but it does not select that window and does not 920make the buffer current. The identity of the selected window is 921unaltered by this function. @var{buffer-or-name} must be a buffer, or 922the name of an existing buffer. 923 924If @var{not-this-window} is non-@code{nil}, it means to display the 925specified buffer in a window other than the selected one, even if it is 926already on display in the selected window. This can cause the buffer to 927appear in two windows at once. Otherwise, if @var{buffer-or-name} is 928already being displayed in any window, that is good enough, so this 929function does nothing. 930 931@code{display-buffer} returns the window chosen to display 932@var{buffer-or-name}. 933 934If the argument @var{frame} is non-@code{nil}, it specifies which frames 935to check when deciding whether the buffer is already displayed. If the 936buffer is already displayed in some window on one of these frames, 937@code{display-buffer} simply returns that window. Here are the possible 938values of @var{frame}: 939 940@itemize @bullet 941@item 942If it is @code{nil}, consider windows on the selected frame. 943(Actually, the last non-minibuffer frame.) 944@item 945If it is @code{t}, consider windows on all frames. 946@item 947If it is @code{visible}, consider windows on all visible frames. 948@item 949If it is 0, consider windows on all visible or iconified frames. 950@item 951If it is a frame, consider windows on that frame. 952@end itemize 953 954Precisely how @code{display-buffer} finds or creates a window depends on 955the variables described below. 956@end deffn 957 958@defopt display-buffer-reuse-frames 959If this variable is non-@code{nil}, @code{display-buffer} searches 960existing frames for a window displaying the buffer. If the buffer is 961already displayed in a window in some frame, @code{display-buffer} makes 962the frame visible and raises it, to use that window. If the buffer is 963not already displayed, or if @code{display-buffer-reuse-frames} is 964@code{nil}, @code{display-buffer}'s behavior is determined by other 965variables, described below. 966@end defopt 967 968@defopt pop-up-windows 969This variable controls whether @code{display-buffer} makes new windows. 970If it is non-@code{nil} and there is only one window, then that window 971is split. If it is @code{nil}, then @code{display-buffer} does not 972split the single window, but uses it whole. 973@end defopt 974 975@defopt split-height-threshold 976This variable determines when @code{display-buffer} may split a window, 977if there are multiple windows. @code{display-buffer} always splits the 978largest window if it has at least this many lines. If the largest 979window is not this tall, it is split only if it is the sole window and 980@code{pop-up-windows} is non-@code{nil}. 981@end defopt 982 983@defopt even-window-heights 984This variable determines if @code{display-buffer} should even out window 985heights if the buffer gets displayed in an existing window, above or 986beneath another existing window. If @code{even-window-heights} is 987@code{t}, the default, window heights will be evened out. If 988@code{even-window-heights} is @code{nil}, the original window heights 989will be left alone. 990@end defopt 991 992@c Emacs 19 feature 993@defopt pop-up-frames 994This variable controls whether @code{display-buffer} makes new frames. 995If it is non-@code{nil}, @code{display-buffer} looks for an existing 996window already displaying the desired buffer, on any visible frame. If 997it finds one, it returns that window. Otherwise it makes a new frame. 998The variables @code{pop-up-windows} and @code{split-height-threshold} do 999not matter if @code{pop-up-frames} is non-@code{nil}. 1000 1001If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either 1002splits a window or reuses one. 1003 1004@xref{Frames}, for more information. 1005@end defopt 1006 1007@c Emacs 19 feature 1008@defopt pop-up-frame-function 1009This variable specifies how to make a new frame if @code{pop-up-frames} 1010is non-@code{nil}. 1011 1012Its value should be a function of no arguments. When 1013@code{display-buffer} makes a new frame, it does so by calling that 1014function, which should return a frame. The default value of the 1015variable is a function that creates a frame using parameters from 1016@code{pop-up-frame-alist}. 1017@end defopt 1018 1019@defopt pop-up-frame-alist 1020This variable holds an alist specifying frame parameters used when 1021@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for 1022more information about frame parameters. 1023@end defopt 1024 1025@defopt special-display-buffer-names 1026A list of buffer names for buffers that should be displayed specially. 1027If the buffer's name is in this list, @code{display-buffer} handles the 1028buffer specially. 1029 1030By default, special display means to give the buffer a dedicated frame. 1031 1032If an element is a list, instead of a string, then the @sc{car} of the 1033list is the buffer name, and the rest of the list says how to create 1034the frame. There are two possibilities for the rest of the list (its 1035@sc{cdr}). It can be an alist, specifying frame parameters, or it can 1036contain a function and arguments to give to it. (The function's first 1037argument is always the buffer to be displayed; the arguments from the 1038list come after that.) 1039 1040For example: 1041 1042@example 1043(("myfile" (minibuffer) (menu-bar-lines . 0))) 1044@end example 1045 1046@noindent 1047specifies to display a buffer named @samp{myfile} in a dedicated frame 1048with specified @code{minibuffer} and @code{menu-bar-lines} parameters. 1049 1050The list of frame parameters can also use the phony frame parameters 1051@code{same-frame} and @code{same-window}. If the specified frame 1052parameters include @code{(same-window . @var{value})} and @var{value} 1053is non-@code{nil}, that means to display the buffer in the current 1054selected window. Otherwise, if they include @code{(same-frame . 1055@var{value})} and @var{value} is non-@code{nil}, that means to display 1056the buffer in a new window in the currently selected frame. 1057@end defopt 1058 1059@defopt special-display-regexps 1060A list of regular expressions that specify buffers that should be 1061displayed specially. If the buffer's name matches any of the regular 1062expressions in this list, @code{display-buffer} handles the buffer 1063specially. 1064 1065By default, special display means to give the buffer a dedicated frame. 1066 1067If an element is a list, instead of a string, then the @sc{car} of the 1068list is the regular expression, and the rest of the list says how to 1069create the frame. See above, under @code{special-display-buffer-names}. 1070@end defopt 1071 1072@defun special-display-p buffer-name 1073This function returns non-@code{nil} if displaying a buffer 1074named @var{buffer-name} with @code{display-buffer} would 1075create a special frame. The value is @code{t} if it would 1076use the default frame parameters, or else the specified list 1077of frame parameters. 1078@end defun 1079 1080@defvar special-display-function 1081This variable holds the function to call to display a buffer specially. 1082It receives the buffer as an argument, and should return the window in 1083which it is displayed. 1084 1085The default value of this variable is 1086@code{special-display-popup-frame}. 1087@end defvar 1088 1089@defun special-display-popup-frame buffer &optional args 1090This function makes @var{buffer} visible in a frame of its own. If 1091@var{buffer} is already displayed in a window in some frame, it makes 1092the frame visible and raises it, to use that window. Otherwise, it 1093creates a frame that will be dedicated to @var{buffer}. This 1094function returns the window it used. 1095 1096If @var{args} is an alist, it specifies frame parameters for the new 1097frame. 1098 1099If @var{args} is a list whose @sc{car} is a symbol, then @code{(car 1100@var{args})} is called as a function to actually create and set up the 1101frame; it is called with @var{buffer} as first argument, and @code{(cdr 1102@var{args})} as additional arguments. 1103 1104This function always uses an existing window displaying @var{buffer}, 1105whether or not it is in a frame of its own; but if you set up the above 1106variables in your init file, before @var{buffer} was created, then 1107presumably the window was previously made by this function. 1108@end defun 1109 1110@defopt special-display-frame-alist 1111@anchor{Definition of special-display-frame-alist} 1112This variable holds frame parameters for 1113@code{special-display-popup-frame} to use when it creates a frame. 1114@end defopt 1115 1116@defopt same-window-buffer-names 1117A list of buffer names for buffers that should be displayed in the 1118selected window. If the buffer's name is in this list, 1119@code{display-buffer} handles the buffer by switching to it in the 1120selected window. 1121@end defopt 1122 1123@defopt same-window-regexps 1124A list of regular expressions that specify buffers that should be 1125displayed in the selected window. If the buffer's name matches any of 1126the regular expressions in this list, @code{display-buffer} handles the 1127buffer by switching to it in the selected window. 1128@end defopt 1129 1130@defun same-window-p buffer-name 1131This function returns @code{t} if displaying a buffer 1132named @var{buffer-name} with @code{display-buffer} would 1133put it in the selected window. 1134@end defun 1135 1136@c Emacs 19 feature 1137@defvar display-buffer-function 1138This variable is the most flexible way to customize the behavior of 1139@code{display-buffer}. If it is non-@code{nil}, it should be a function 1140that @code{display-buffer} calls to do the work. The function should 1141accept two arguments, the first two arguments that @code{display-buffer} 1142received. It should choose or create a window, display the specified 1143buffer in it, and then return the window. 1144 1145This hook takes precedence over all the other options and hooks 1146described above. 1147@end defvar 1148 1149@c Emacs 19 feature 1150@cindex dedicated window 1151A window can be marked as ``dedicated'' to its buffer. Then 1152@code{display-buffer} will not try to use that window to display any 1153other buffer. 1154 1155@defun window-dedicated-p window 1156This function returns non-@code{nil} if @var{window} is marked as 1157dedicated; otherwise @code{nil}. 1158@end defun 1159 1160@defun set-window-dedicated-p window flag 1161This function marks @var{window} as dedicated if @var{flag} is 1162non-@code{nil}, and nondedicated otherwise. 1163@end defun 1164 1165@node Window Point 1166@section Windows and Point 1167@cindex window position 1168@cindex window point 1169@cindex position in window 1170@cindex point in window 1171 1172 Each window has its own value of point, independent of the value of 1173point in other windows displaying the same buffer. This makes it useful 1174to have multiple windows showing one buffer. 1175 1176@itemize @bullet 1177@item 1178The window point is established when a window is first created; it is 1179initialized from the buffer's point, or from the window point of another 1180window opened on the buffer if such a window exists. 1181 1182@item 1183Selecting a window sets the value of point in its buffer from the 1184window's value of point. Conversely, deselecting a window sets the 1185window's value of point from that of the buffer. Thus, when you switch 1186between windows that display a given buffer, the point value for the 1187selected window is in effect in the buffer, while the point values for 1188the other windows are stored in those windows. 1189 1190@item 1191As long as the selected window displays the current buffer, the window's 1192point and the buffer's point always move together; they remain equal. 1193@end itemize 1194 1195@noindent 1196@xref{Positions}, for more details on buffer positions. 1197 1198@cindex cursor 1199 As far as the user is concerned, point is where the cursor is, and 1200when the user switches to another buffer, the cursor jumps to the 1201position of point in that buffer. 1202 1203@defun window-point &optional window 1204This function returns the current position of point in @var{window}. 1205For a nonselected window, this is the value point would have (in that 1206window's buffer) if that window were selected. If @var{window} is 1207@code{nil}, the selected window is used. 1208 1209When @var{window} is the selected window and its buffer is also the 1210current buffer, the value returned is the same as point in that buffer. 1211 1212Strictly speaking, it would be more correct to return the 1213``top-level'' value of point, outside of any @code{save-excursion} 1214forms. But that value is hard to find. 1215@end defun 1216 1217@defun set-window-point window position 1218This function positions point in @var{window} at position 1219@var{position} in @var{window}'s buffer. It returns @var{position}. 1220 1221If @var{window} is selected, and its buffer is current, 1222this simply does @code{goto-char}. 1223@end defun 1224 1225@node Window Start 1226@section The Window Start Position 1227@cindex window start position 1228 1229 Each window contains a marker used to keep track of a buffer position 1230that specifies where in the buffer display should start. This position 1231is called the @dfn{display-start} position of the window (or just the 1232@dfn{start}). The character after this position is the one that appears 1233at the upper left corner of the window. It is usually, but not 1234inevitably, at the beginning of a text line. 1235 1236@defun window-start &optional window 1237@cindex window top line 1238This function returns the display-start position of window 1239@var{window}. If @var{window} is @code{nil}, the selected window is 1240used. For example, 1241 1242@example 1243@group 1244(window-start) 1245 @result{} 7058 1246@end group 1247@end example 1248 1249When you create a window, or display a different buffer in it, the 1250display-start position is set to a display-start position recently used 1251for the same buffer, or 1 if the buffer doesn't have any. 1252 1253Redisplay updates the window-start position (if you have not specified 1254it explicitly since the previous redisplay)---for example, to make sure 1255point appears on the screen. Nothing except redisplay automatically 1256changes the window-start position; if you move point, do not expect the 1257window-start position to change in response until after the next 1258redisplay. 1259 1260For a realistic example of using @code{window-start}, see the 1261description of @code{count-lines}. @xref{Definition of count-lines}. 1262@end defun 1263 1264@defun window-end &optional window update 1265This function returns the position of the end of the display in window 1266@var{window}. If @var{window} is @code{nil}, the selected window is 1267used. 1268 1269Simply changing the buffer text or moving point does not update the 1270value that @code{window-end} returns. The value is updated only when 1271Emacs redisplays and redisplay completes without being preempted. 1272 1273If the last redisplay of @var{window} was preempted, and did not finish, 1274Emacs does not know the position of the end of display in that window. 1275In that case, this function returns @code{nil}. 1276 1277If @var{update} is non-@code{nil}, @code{window-end} always returns an 1278up-to-date value for where the window ends, based on the current 1279@code{window-start} value. If the saved value is valid, 1280@code{window-end} returns that; otherwise it computes the correct 1281value by scanning the buffer text. 1282 1283Even if @var{update} is non-@code{nil}, @code{window-end} does not 1284attempt to scroll the display if point has moved off the screen, the 1285way real redisplay would do. It does not alter the 1286@code{window-start} value. In effect, it reports where the displayed 1287text will end if scrolling is not required. 1288@end defun 1289 1290@defun set-window-start window position &optional noforce 1291This function sets the display-start position of @var{window} to 1292@var{position} in @var{window}'s buffer. It returns @var{position}. 1293 1294The display routines insist that the position of point be visible when a 1295buffer is displayed. Normally, they change the display-start position 1296(that is, scroll the window) whenever necessary to make point visible. 1297However, if you specify the start position with this function using 1298@code{nil} for @var{noforce}, it means you want display to start at 1299@var{position} even if that would put the location of point off the 1300screen. If this does place point off screen, the display routines move 1301point to the left margin on the middle line in the window. 1302 1303For example, if point @w{is 1} and you set the start of the window @w{to 13042}, then point would be ``above'' the top of the window. The display 1305routines will automatically move point if it is still 1 when redisplay 1306occurs. Here is an example: 1307 1308@example 1309@group 1310;; @r{Here is what @samp{foo} looks like before executing} 1311;; @r{the @code{set-window-start} expression.} 1312@end group 1313 1314@group 1315---------- Buffer: foo ---------- 1316@point{}This is the contents of buffer foo. 13172 13183 13194 13205 13216 1322---------- Buffer: foo ---------- 1323@end group 1324 1325@group 1326(set-window-start 1327 (selected-window) 1328 (1+ (window-start))) 1329@result{} 2 1330@end group 1331 1332@group 1333;; @r{Here is what @samp{foo} looks like after executing} 1334;; @r{the @code{set-window-start} expression.} 1335---------- Buffer: foo ---------- 1336his is the contents of buffer foo. 13372 13383 1339@point{}4 13405 13416 1342---------- Buffer: foo ---------- 1343@end group 1344@end example 1345 1346If @var{noforce} is non-@code{nil}, and @var{position} would place point 1347off screen at the next redisplay, then redisplay computes a new window-start 1348position that works well with point, and thus @var{position} is not used. 1349@end defun 1350 1351@defun pos-visible-in-window-p &optional position window partially 1352This function returns non-@code{nil} if @var{position} is within the 1353range of text currently visible on the screen in @var{window}. It 1354returns @code{nil} if @var{position} is scrolled vertically out of 1355view. Locations that are partially obscured are not considered 1356visible unless @var{partially} is non-@code{nil}. The argument 1357@var{position} defaults to the current position of point in 1358@var{window}; @var{window}, to the selected window. 1359 1360If @var{position} is @code{t}, that means to check the last visible 1361position in @var{window}. 1362 1363The @code{pos-visible-in-window-p} function considers only vertical 1364scrolling. If @var{position} is out of view only because @var{window} 1365has been scrolled horizontally, @code{pos-visible-in-window-p} returns 1366non-@code{nil} anyway. @xref{Horizontal Scrolling}. 1367 1368If @var{position} is visible, @code{pos-visible-in-window-p} returns 1369@code{t} if @var{partially} is @code{nil}; if @var{partially} is 1370non-@code{nil}, and the character after @var{position} is fully 1371visible, it returns a list of the form @code{(@var{x} @var{y})}, where 1372@var{x} and @var{y} are the pixel coordinates relative to the top left 1373corner of the window; otherwise it returns an extended list of the 1374form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} 1375@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number 1376of off-window pixels at the top and bottom of the row at 1377@var{position}, @var{rowh} specifies the visible height of that row, 1378and @var{vpos} specifies the vertical position (zero-based row number) 1379of that row. 1380 1381Here is an example: 1382 1383@example 1384@group 1385;; @r{If point is off the screen now, recenter it now.} 1386(or (pos-visible-in-window-p 1387 (point) (selected-window)) 1388 (recenter 0)) 1389@end group 1390@end example 1391@end defun 1392 1393@defun window-line-height &optional line window 1394This function returns information about text line @var{line} in @var{window}. 1395If @var{line} is one of @code{header-line} or @code{mode-line}, 1396@code{window-line-height} returns information about the corresponding 1397line of the window. Otherwise, @var{line} is a text line number 1398starting from 0. A negative number counts from the end of the window. 1399The argument @var{line} defaults to the current line in @var{window}; 1400@var{window}, to the selected window. 1401 1402If the display is not up to date, @code{window-line-height} returns 1403@code{nil}. In that case, @code{pos-visible-in-window-p} may be used 1404to obtain related information. 1405 1406If there is no line corresponding to the specified @var{line}, 1407@code{window-line-height} returns @code{nil}. Otherwise, it returns 1408a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, 1409where @var{height} is the height in pixels of the visible part of the 1410line, @var{vpos} and @var{ypos} are the vertical position in lines and 1411pixels of the line relative to the top of the first text line, and 1412@var{offbot} is the number of off-window pixels at the bottom of the 1413text line. If there are off-window pixels at the top of the (first) 1414text line, @var{ypos} is negative. 1415@end defun 1416 1417@node Textual Scrolling 1418@section Textual Scrolling 1419@cindex textual scrolling 1420@cindex scrolling textually 1421 1422 @dfn{Textual scrolling} means moving the text up or down through a 1423window. It works by changing the value of the window's display-start 1424location. It may also change the value of @code{window-point} to keep 1425point on the screen. 1426 1427 Textual scrolling was formerly called ``vertical scrolling,'' but we 1428changed its name to distinguish it from the new vertical fractional 1429scrolling feature (@pxref{Vertical Scrolling}). 1430 1431 In the commands @code{scroll-up} and @code{scroll-down}, the directions 1432``up'' and ``down'' refer to the motion of the text in the buffer at which 1433you are looking through the window. Imagine that the text is 1434written on a long roll of paper and that the scrolling commands move the 1435paper up and down. Thus, if you are looking at text in the middle of a 1436buffer and repeatedly call @code{scroll-down}, you will eventually see 1437the beginning of the buffer. 1438 1439 Some people have urged that the opposite convention be used: they 1440imagine that the window moves over text that remains in place. Then 1441``down'' commands would take you to the end of the buffer. This view is 1442more consistent with the actual relationship between windows and the 1443text in the buffer, but it is less like what the user sees. The 1444position of a window on the terminal does not move, and short scrolling 1445commands clearly move the text up or down on the screen. We have chosen 1446names that fit the user's point of view. 1447 1448 The textual scrolling functions (aside from 1449@code{scroll-other-window}) have unpredictable results if the current 1450buffer is different from the buffer that is displayed in the selected 1451window. @xref{Current Buffer}. 1452 1453 If the window contains a row which is taller than the height of the 1454window (for example in the presence of a large image), the scroll 1455functions will adjust the window vscroll to scroll the partially 1456visible row. To disable this feature, Lisp code may bind the variable 1457`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}). 1458 1459@deffn Command scroll-up &optional count 1460This function scrolls the text in the selected window upward 1461@var{count} lines. If @var{count} is negative, scrolling is actually 1462downward. 1463 1464If @var{count} is @code{nil} (or omitted), then the length of scroll 1465is @code{next-screen-context-lines} lines less than the usable height of 1466the window (not counting its mode line). 1467 1468@code{scroll-up} returns @code{nil}, unless it gets an error 1469because it can't scroll any further. 1470@end deffn 1471 1472@deffn Command scroll-down &optional count 1473This function scrolls the text in the selected window downward 1474@var{count} lines. If @var{count} is negative, scrolling is actually 1475upward. 1476 1477If @var{count} is omitted or @code{nil}, then the length of the scroll 1478is @code{next-screen-context-lines} lines less than the usable height of 1479the window (not counting its mode line). 1480 1481@code{scroll-down} returns @code{nil}, unless it gets an error because 1482it can't scroll any further. 1483@end deffn 1484 1485@deffn Command scroll-other-window &optional count 1486This function scrolls the text in another window upward @var{count} 1487lines. Negative values of @var{count}, or @code{nil}, are handled 1488as in @code{scroll-up}. 1489 1490You can specify which buffer to scroll by setting the variable 1491@code{other-window-scroll-buffer} to a buffer. If that buffer isn't 1492already displayed, @code{scroll-other-window} displays it in some 1493window. 1494 1495When the selected window is the minibuffer, the next window is normally 1496the one at the top left corner. You can specify a different window to 1497scroll, when the minibuffer is selected, by setting the variable 1498@code{minibuffer-scroll-window}. This variable has no effect when any 1499other window is selected. When it is non-@code{nil} and the 1500minibuffer is selected, it takes precedence over 1501@code{other-window-scroll-buffer}. @xref{Definition of 1502minibuffer-scroll-window}. 1503 1504When the minibuffer is active, it is the next window if the selected 1505window is the one at the bottom right corner. In this case, 1506@code{scroll-other-window} attempts to scroll the minibuffer. If the 1507minibuffer contains just one line, it has nowhere to scroll to, so the 1508line reappears after the echo area momentarily displays the message 1509@samp{Beginning of buffer}. 1510@end deffn 1511 1512@c Emacs 19 feature 1513@defvar other-window-scroll-buffer 1514If this variable is non-@code{nil}, it tells @code{scroll-other-window} 1515which buffer to scroll. 1516@end defvar 1517 1518@defopt scroll-margin 1519This option specifies the size of the scroll margin---a minimum number 1520of lines between point and the top or bottom of a window. Whenever 1521point gets within this many lines of the top or bottom of the window, 1522redisplay scrolls the text automatically (if possible) to move point 1523out of the margin, closer to the center of the window. 1524@end defopt 1525 1526@defopt scroll-conservatively 1527This variable controls how scrolling is done automatically when point 1528moves off the screen (or into the scroll margin). If the value is a 1529positive integer @var{n}, then redisplay scrolls the text up to 1530@var{n} lines in either direction, if that will bring point back into 1531proper view. This action is called @dfn{conservative scrolling}. 1532Otherwise, scrolling happens in the usual way, under the control of 1533other variables such as @code{scroll-up-aggressively} and 1534@code{scroll-down-aggressively}. 1535 1536The default value is zero, which means that conservative scrolling 1537never happens. 1538@end defopt 1539 1540@defopt scroll-down-aggressively 1541The value of this variable should be either @code{nil} or a fraction 1542@var{f} between 0 and 1. If it is a fraction, that specifies where on 1543the screen to put point when scrolling down. More precisely, when a 1544window scrolls down because point is above the window start, the new 1545start position is chosen to put point @var{f} part of the window 1546height from the top. The larger @var{f}, the more aggressive the 1547scrolling. 1548 1549A value of @code{nil} is equivalent to .5, since its effect is to center 1550point. This variable automatically becomes buffer-local when set in any 1551fashion. 1552@end defopt 1553 1554@defopt scroll-up-aggressively 1555Likewise, for scrolling up. The value, @var{f}, specifies how far 1556point should be placed from the bottom of the window; thus, as with 1557@code{scroll-up-aggressively}, a larger value scrolls more aggressively. 1558@end defopt 1559 1560@defopt scroll-step 1561This variable is an older variant of @code{scroll-conservatively}. The 1562difference is that it if its value is @var{n}, that permits scrolling 1563only by precisely @var{n} lines, not a smaller number. This feature 1564does not work with @code{scroll-margin}. The default value is zero. 1565@end defopt 1566 1567@defopt scroll-preserve-screen-position 1568If this option is @code{t}, scrolling which would move the current 1569point position out of the window chooses the new position of point 1570so that the vertical position of the cursor is unchanged, if possible. 1571 1572If it is non-@code{nil} and not @code{t}, then the scrolling functions 1573always preserve the vertical position of point, if possible. 1574@end defopt 1575 1576@defopt next-screen-context-lines 1577The value of this variable is the number of lines of continuity to 1578retain when scrolling by full screens. For example, @code{scroll-up} 1579with an argument of @code{nil} scrolls so that this many lines at the 1580bottom of the window appear instead at the top. The default value is 1581@code{2}. 1582@end defopt 1583 1584@deffn Command recenter &optional count 1585@cindex centering point 1586This function scrolls the text in the selected window so that point is 1587displayed at a specified vertical position within the window. It does 1588not ``move point'' with respect to the text. 1589 1590If @var{count} is a nonnegative number, that puts the line containing 1591point @var{count} lines down from the top of the window. If 1592@var{count} is a negative number, then it counts upward from the 1593bottom of the window, so that @minus{}1 stands for the last usable 1594line in the window. If @var{count} is a non-@code{nil} list, then it 1595stands for the line in the middle of the window. 1596 1597If @var{count} is @code{nil}, @code{recenter} puts the line containing 1598point in the middle of the window, then clears and redisplays the entire 1599selected frame. 1600 1601When @code{recenter} is called interactively, @var{count} is the raw 1602prefix argument. Thus, typing @kbd{C-u} as the prefix sets the 1603@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets 1604@var{count} to 4, which positions the current line four lines from the 1605top. 1606 1607With an argument of zero, @code{recenter} positions the current line at 1608the top of the window. This action is so handy that some people make a 1609separate key binding to do this. For example, 1610 1611@example 1612@group 1613(defun line-to-top-of-window () 1614 "Scroll current line to top of window. 1615Replaces three keystroke sequence C-u 0 C-l." 1616 (interactive) 1617 (recenter 0)) 1618 1619(global-set-key [kp-multiply] 'line-to-top-of-window) 1620@end group 1621@end example 1622@end deffn 1623 1624@node Vertical Scrolling 1625@section Vertical Fractional Scrolling 1626@cindex vertical fractional scrolling 1627 1628 @dfn{Vertical fractional scrolling} means shifting the image in the 1629window up or down by a specified multiple or fraction of a line. 1630Each window has a @dfn{vertical scroll position}, 1631which is a number, never less than zero. It specifies how far to raise 1632the contents of the window. Raising the window contents generally makes 1633all or part of some lines disappear off the top, and all or part of some 1634other lines appear at the bottom. The usual value is zero. 1635 1636 The vertical scroll position is measured in units of the normal line 1637height, which is the height of the default font. Thus, if the value is 1638.5, that means the window contents are scrolled up half the normal line 1639height. If it is 3.3, that means the window contents are scrolled up 1640somewhat over three times the normal line height. 1641 1642 What fraction of a line the vertical scrolling covers, or how many 1643lines, depends on what the lines contain. A value of .5 could scroll a 1644line whose height is very short off the screen, while a value of 3.3 1645could scroll just part of the way through a tall line or an image. 1646 1647@defun window-vscroll &optional window pixels-p 1648This function returns the current vertical scroll position of 1649@var{window}. If @var{window} is @code{nil}, the selected window is 1650used. If @var{pixels-p} is non-@code{nil}, the return value is 1651measured in pixels, rather than in units of the normal line height. 1652 1653@example 1654@group 1655(window-vscroll) 1656 @result{} 0 1657@end group 1658@end example 1659@end defun 1660 1661@defun set-window-vscroll window lines &optional pixels-p 1662This function sets @var{window}'s vertical scroll position to 1663@var{lines}. The argument @var{lines} should be zero or positive; if 1664not, it is taken as zero. 1665 1666If @var{window} is @code{nil}, the selected window is used. 1667 1668The actual vertical scroll position must always correspond 1669to an integral number of pixels, so the value you specify 1670is rounded accordingly. 1671 1672The return value is the result of this rounding. 1673 1674@example 1675@group 1676(set-window-vscroll (selected-window) 1.2) 1677 @result{} 1.13 1678@end group 1679@end example 1680 1681If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of 1682pixels. In this case, the return value is @var{lines}. 1683@end defun 1684 1685@defvar auto-window-vscroll 1686If this variable is non-@code{nil}, the line-move, scroll-up, and 1687scroll-down functions will automatically modify the window vscroll to 1688scroll through display rows that are taller that the height of the 1689window, for example in the presence of large images. 1690@end defvar 1691 1692@node Horizontal Scrolling 1693@section Horizontal Scrolling 1694@cindex horizontal scrolling 1695 1696 @dfn{Horizontal scrolling} means shifting the image in the window left 1697or right by a specified multiple of the normal character width. Each 1698window has a @dfn{horizontal scroll position}, which is a number, never 1699less than zero. It specifies how far to shift the contents left. 1700Shifting the window contents left generally makes all or part of some 1701characters disappear off the left, and all or part of some other 1702characters appear at the right. The usual value is zero. 1703 1704 The horizontal scroll position is measured in units of the normal 1705character width, which is the width of space in the default font. Thus, 1706if the value is 5, that means the window contents are scrolled left by 5 1707times the normal character width. How many characters actually 1708disappear off to the left depends on their width, and could vary from 1709line to line. 1710 1711 Because we read from side to side in the ``inner loop,'' and from top 1712to bottom in the ``outer loop,'' the effect of horizontal scrolling is 1713not like that of textual or vertical scrolling. Textual scrolling 1714involves selection of a portion of text to display, and vertical 1715scrolling moves the window contents contiguously; but horizontal 1716scrolling causes part of @emph{each line} to go off screen. 1717 1718 Usually, no horizontal scrolling is in effect; then the leftmost 1719column is at the left edge of the window. In this state, scrolling to 1720the right is meaningless, since there is no data to the left of the edge 1721to be revealed by it; so this is not allowed. Scrolling to the left is 1722allowed; it scrolls the first columns of text off the edge of the window 1723and can reveal additional columns on the right that were truncated 1724before. Once a window has a nonzero amount of leftward horizontal 1725scrolling, you can scroll it back to the right, but only so far as to 1726reduce the net horizontal scroll to zero. There is no limit to how far 1727left you can scroll, but eventually all the text will disappear off the 1728left edge. 1729 1730@vindex auto-hscroll-mode 1731 If @code{auto-hscroll-mode} is set, redisplay automatically alters 1732the horizontal scrolling of a window as necessary to ensure that point 1733is always visible. However, you can still set the horizontal 1734scrolling value explicitly. The value you specify serves as a lower 1735bound for automatic scrolling, i.e. automatic scrolling will not 1736scroll a window to a column less than the specified one. 1737 1738@deffn Command scroll-left &optional count set-minimum 1739This function scrolls the selected window @var{count} columns to the 1740left (or to the right if @var{count} is negative). The default 1741for @var{count} is the window width, minus 2. 1742 1743The return value is the total amount of leftward horizontal scrolling in 1744effect after the change---just like the value returned by 1745@code{window-hscroll} (below). 1746 1747Once you scroll a window as far right as it can go, back to its normal 1748position where the total leftward scrolling is zero, attempts to scroll 1749any farther right have no effect. 1750 1751If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes 1752the lower bound for automatic scrolling; that is, automatic scrolling 1753will not scroll a window to a column less than the value returned by 1754this function. Interactive calls pass non-@code{nil} for 1755@var{set-minimum}. 1756@end deffn 1757 1758@deffn Command scroll-right &optional count set-minimum 1759This function scrolls the selected window @var{count} columns to the 1760right (or to the left if @var{count} is negative). The default 1761for @var{count} is the window width, minus 2. Aside from the direction 1762of scrolling, this works just like @code{scroll-left}. 1763@end deffn 1764 1765@defun window-hscroll &optional window 1766This function returns the total leftward horizontal scrolling of 1767@var{window}---the number of columns by which the text in @var{window} 1768is scrolled left past the left margin. 1769 1770The value is never negative. It is zero when no horizontal scrolling 1771has been done in @var{window} (which is usually the case). 1772 1773If @var{window} is @code{nil}, the selected window is used. 1774 1775@example 1776@group 1777(window-hscroll) 1778 @result{} 0 1779@end group 1780@group 1781(scroll-left 5) 1782 @result{} 5 1783@end group 1784@group 1785(window-hscroll) 1786 @result{} 5 1787@end group 1788@end example 1789@end defun 1790 1791@defun set-window-hscroll window columns 1792This function sets horizontal scrolling of @var{window}. The value of 1793@var{columns} specifies the amount of scrolling, in terms of columns 1794from the left margin. The argument @var{columns} should be zero or 1795positive; if not, it is taken as zero. Fractional values of 1796@var{columns} are not supported at present. 1797 1798Note that @code{set-window-hscroll} may appear not to work if you test 1799it by evaluating a call with @kbd{M-:} in a simple way. What happens 1800is that the function sets the horizontal scroll value and returns, but 1801then redisplay adjusts the horizontal scrolling to make point visible, 1802and this overrides what the function did. You can observe the 1803function's effect if you call it while point is sufficiently far from 1804the left margin that it will remain visible. 1805 1806The value returned is @var{columns}. 1807 1808@example 1809@group 1810(set-window-hscroll (selected-window) 10) 1811 @result{} 10 1812@end group 1813@end example 1814@end defun 1815 1816 Here is how you can determine whether a given position @var{position} 1817is off the screen due to horizontal scrolling: 1818 1819@example 1820@group 1821(defun hscroll-on-screen (window position) 1822 (save-excursion 1823 (goto-char position) 1824 (and 1825 (>= (- (current-column) (window-hscroll window)) 0) 1826 (< (- (current-column) (window-hscroll window)) 1827 (window-width window))))) 1828@end group 1829@end example 1830 1831@node Size of Window 1832@section The Size of a Window 1833@cindex window size 1834@cindex size of window 1835 1836 An Emacs window is rectangular, and its size information consists of 1837the height (the number of lines) and the width (the number of character 1838positions in each line). The mode line is included in the height. But 1839the width does not count the scroll bar or the column of @samp{|} 1840characters that separates side-by-side windows. 1841 1842 The following three functions return size information about a window: 1843 1844@defun window-height &optional window 1845This function returns the number of lines in @var{window}, including 1846its mode line and header line, if any. If @var{window} fills its 1847entire frame except for the echo area, this is typically one less than 1848the value of @code{frame-height} on that frame. 1849 1850If @var{window} is @code{nil}, the function uses the selected window. 1851 1852@example 1853@group 1854(window-height) 1855 @result{} 23 1856@end group 1857@group 1858(split-window-vertically) 1859 @result{} #<window 4 on windows.texi> 1860@end group 1861@group 1862(window-height) 1863 @result{} 11 1864@end group 1865@end example 1866@end defun 1867 1868@defun window-body-height &optional window 1869Like @code{window-height} but the value does not include the 1870mode line (if any) or the header line (if any). 1871@end defun 1872 1873@defun window-width &optional window 1874This function returns the number of columns in @var{window}. If 1875@var{window} fills its entire frame, this is the same as the value of 1876@code{frame-width} on that frame. The width does not include the 1877window's scroll bar or the column of @samp{|} characters that separates 1878side-by-side windows. 1879 1880If @var{window} is @code{nil}, the function uses the selected window. 1881 1882@example 1883@group 1884(window-width) 1885 @result{} 80 1886@end group 1887@end example 1888@end defun 1889 1890@defun window-edges &optional window 1891This function returns a list of the edge coordinates of @var{window}. 1892If @var{window} is @code{nil}, the selected window is used. 1893 1894The order of the list is @code{(@var{left} @var{top} @var{right} 1895@var{bottom})}, all elements relative to 0, 0 at the top left corner of 1896the frame. The element @var{right} of the value is one more than the 1897rightmost column used by @var{window}, and @var{bottom} is one more than 1898the bottommost row used by @var{window} and its mode-line. 1899 1900The edges include the space used by the window's scroll bar, display 1901margins, fringes, header line, and mode line, if it has them. Also, 1902if the window has a neighbor on the right, its right edge value 1903includes the width of the separator line between the window and that 1904neighbor. Since the width of the window does not include this 1905separator, the width does not usually equal the difference between the 1906right and left edges. 1907@end defun 1908 1909@defun window-inside-edges &optional window 1910This is similar to @code{window-edges}, but the edge values 1911it returns include only the text area of the window. They 1912do not include the header line, mode line, scroll bar or 1913vertical separator, fringes, or display margins. 1914@end defun 1915 1916Here are the results obtained on a typical 24-line terminal with just 1917one window, with menu bar enabled: 1918 1919@example 1920@group 1921(window-edges (selected-window)) 1922 @result{} (0 1 80 23) 1923@end group 1924@group 1925(window-inside-edges (selected-window)) 1926 @result{} (0 1 80 22) 1927@end group 1928@end example 1929 1930@noindent 1931The bottom edge is at line 23 because the last line is the echo area. 1932The bottom inside edge is at line 22, which is the window's mode line. 1933 1934If @var{window} is at the upper left corner of its frame, and there is 1935no menu bar, then @var{bottom} returned by @code{window-edges} is the 1936same as the value of @code{(window-height)}, @var{right} is almost the 1937same as the value of @code{(window-width)}, and @var{top} and 1938@var{left} are zero. For example, the edges of the following window 1939are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 1940columns, the last column of the window (column 7) holds a border 1941rather than text. The last row (row 4) holds the mode line, shown 1942here with @samp{xxxxxxxxx}. 1943 1944@example 1945@group 1946 0 1947 _______ 1948 0 | | 1949 | | 1950 | | 1951 | | 1952 xxxxxxxxx 4 1953 1954 7 1955@end group 1956@end example 1957 1958In the following example, let's suppose that the frame is 7 1959columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} 1960and the edges of the right window are @w{@samp{4 0 7 3}}. 1961The inside edges of the left window are @w{@samp{0 0 3 2}}, 1962and the inside edges of the right window are @w{@samp{4 0 7 2}}, 1963 1964@example 1965@group 1966 ___ ___ 1967 | | | 1968 | | | 1969 xxxxxxxxx 1970 1971 0 34 7 1972@end group 1973@end example 1974 1975@defun window-pixel-edges &optional window 1976This function is like @code{window-edges} except that, on a graphical 1977display, the edge values are measured in pixels instead of in 1978character lines and columns. 1979@end defun 1980 1981@defun window-inside-pixel-edges &optional window 1982This function is like @code{window-inside-edges} except that, on a 1983graphical display, the edge values are measured in pixels instead of 1984in character lines and columns. 1985@end defun 1986 1987@node Resizing Windows 1988@section Changing the Size of a Window 1989@cindex window resizing 1990@cindex resize window 1991@cindex changing window size 1992@cindex window size, changing 1993 1994 The window size functions fall into two classes: high-level commands 1995that change the size of windows and low-level functions that access 1996window size. Emacs does not permit overlapping windows or gaps between 1997windows, so resizing one window affects other windows. 1998 1999@deffn Command enlarge-window size &optional horizontal 2000This function makes the selected window @var{size} lines taller, 2001stealing lines from neighboring windows. It takes the lines from one 2002window at a time until that window is used up, then takes from another. 2003If a window from which lines are stolen shrinks below 2004@code{window-min-height} lines, that window disappears. 2005 2006If @var{horizontal} is non-@code{nil}, this function makes 2007@var{window} wider by @var{size} columns, stealing columns instead of 2008lines. If a window from which columns are stolen shrinks below 2009@code{window-min-width} columns, that window disappears. 2010 2011If the requested size would exceed that of the window's frame, then the 2012function makes the window occupy the entire height (or width) of the 2013frame. 2014 2015If there are various other windows from which lines or columns can be 2016stolen, and some of them specify fixed size (using 2017@code{window-size-fixed}, see below), they are left untouched while 2018other windows are ``robbed.'' If it would be necessary to alter the 2019size of a fixed-size window, @code{enlarge-window} gets an error 2020instead. 2021 2022If @var{size} is negative, this function shrinks the window by 2023@minus{}@var{size} lines or columns. If that makes the window smaller 2024than the minimum size (@code{window-min-height} and 2025@code{window-min-width}), @code{enlarge-window} deletes the window. 2026 2027@code{enlarge-window} returns @code{nil}. 2028@end deffn 2029 2030@deffn Command enlarge-window-horizontally columns 2031This function makes the selected window @var{columns} wider. 2032It could be defined as follows: 2033 2034@example 2035@group 2036(defun enlarge-window-horizontally (columns) 2037 (interactive "p") 2038 (enlarge-window columns t)) 2039@end group 2040@end example 2041@end deffn 2042 2043@deffn Command shrink-window size &optional horizontal 2044This function is like @code{enlarge-window} but negates the argument 2045@var{size}, making the selected window smaller by giving lines (or 2046columns) to the other windows. If the window shrinks below 2047@code{window-min-height} or @code{window-min-width}, then it disappears. 2048 2049If @var{size} is negative, the window is enlarged by @minus{}@var{size} 2050lines or columns. 2051@end deffn 2052 2053@deffn Command shrink-window-horizontally columns 2054This function makes the selected window @var{columns} narrower. 2055It could be defined as follows: 2056 2057@example 2058@group 2059(defun shrink-window-horizontally (columns) 2060 (interactive "p") 2061 (shrink-window columns t)) 2062@end group 2063@end example 2064@end deffn 2065 2066@defun adjust-window-trailing-edge window delta horizontal 2067This function makes the selected window @var{delta} lines taller or 2068@var{delta} columns wider, by moving the bottom or right edge. This 2069function does not delete other windows; if it cannot make the 2070requested size adjustment, it signals an error. On success, this 2071function returns @code{nil}. 2072@end defun 2073 2074@defun fit-window-to-buffer &optional window max-height min-height 2075This function makes @var{window} the right height to display its 2076contents exactly. If @var{window} is omitted or @code{nil}, it uses 2077the selected window. 2078 2079The argument @var{max-height} specifies the maximum height the window 2080is allowed to be; @code{nil} means use the frame height. The argument 2081@var{min-height} specifies the minimum height for the window; 2082@code{nil} means use @code{window-min-height}. All these height 2083values include the mode-line and/or header-line. 2084@end defun 2085 2086@deffn Command shrink-window-if-larger-than-buffer &optional window 2087This command shrinks @var{window} vertically to be as small as 2088possible while still showing the full contents of its buffer---but not 2089less than @code{window-min-height} lines. If @var{window} is not 2090given, it defaults to the selected window. 2091 2092However, the command does nothing if the window is already too small to 2093display the whole text of the buffer, or if part of the contents are 2094currently scrolled off screen, or if the window is not the full width of 2095its frame, or if the window is the only window in its frame. 2096 2097This command returns non-@code{nil} if it actually shrank the window 2098and @code{nil} otherwise. 2099@end deffn 2100 2101@defvar window-size-fixed 2102If this variable is non-@code{nil}, in any given buffer, 2103then the size of any window displaying the buffer remains fixed 2104unless you explicitly change it or Emacs has no other choice. 2105 2106If the value is @code{height}, then only the window's height is fixed; 2107if the value is @code{width}, then only the window's width is fixed. 2108Any other non-@code{nil} value fixes both the width and the height. 2109 2110This variable automatically becomes buffer-local when set. 2111 2112Explicit size-change functions such as @code{enlarge-window} 2113get an error if they would have to change a window size which is fixed. 2114Therefore, when you want to change the size of such a window, 2115you should bind @code{window-size-fixed} to @code{nil}, like this: 2116 2117@example 2118(let ((window-size-fixed nil)) 2119 (enlarge-window 10)) 2120@end example 2121 2122Note that changing the frame size will change the size of a 2123fixed-size window, if there is no other alternative. 2124@end defvar 2125 2126@cindex minimum window size 2127 The following two variables constrain the window-structure-changing 2128functions to a minimum height and width. 2129 2130@defopt window-min-height 2131The value of this variable determines how short a window may become 2132before it is automatically deleted. Making a window smaller than 2133@code{window-min-height} automatically deletes it, and no window may 2134be created shorter than this. The default value is 4. 2135 2136The absolute minimum window height is one; actions that change window 2137sizes reset this variable to one if it is less than one. 2138@end defopt 2139 2140@defopt window-min-width 2141The value of this variable determines how narrow a window may become 2142before it is automatically deleted. Making a window smaller than 2143@code{window-min-width} automatically deletes it, and no window may be 2144created narrower than this. The default value is 10. 2145 2146The absolute minimum window width is two; actions that change window 2147sizes reset this variable to two if it is less than two. 2148@end defopt 2149 2150@node Coordinates and Windows 2151@section Coordinates and Windows 2152 2153This section describes how to relate screen coordinates to windows. 2154 2155@defun window-at x y &optional frame 2156This function returns the window containing the specified cursor 2157position in the frame @var{frame}. The coordinates @var{x} and @var{y} 2158are measured in characters and count from the top left corner of the 2159frame. If they are out of range, @code{window-at} returns @code{nil}. 2160 2161If you omit @var{frame}, the selected frame is used. 2162@end defun 2163 2164@defun coordinates-in-window-p coordinates window 2165This function checks whether a particular frame position falls within 2166the window @var{window}. 2167 2168The argument @var{coordinates} is a cons cell of the form @code{(@var{x} 2169. @var{y})}. The coordinates @var{x} and @var{y} are measured in 2170characters, and count from the top left corner of the screen or frame. 2171 2172The value returned by @code{coordinates-in-window-p} is non-@code{nil} 2173if the coordinates are inside @var{window}. The value also indicates 2174what part of the window the position is in, as follows: 2175 2176@table @code 2177@item (@var{relx} . @var{rely}) 2178The coordinates are inside @var{window}. The numbers @var{relx} and 2179@var{rely} are the equivalent window-relative coordinates for the 2180specified position, counting from 0 at the top left corner of the 2181window. 2182 2183@item mode-line 2184The coordinates are in the mode line of @var{window}. 2185 2186@item header-line 2187The coordinates are in the header line of @var{window}. 2188 2189@item vertical-line 2190The coordinates are in the vertical line between @var{window} and its 2191neighbor to the right. This value occurs only if the window doesn't 2192have a scroll bar; positions in a scroll bar are considered outside the 2193window for these purposes. 2194 2195@item left-fringe 2196@itemx right-fringe 2197The coordinates are in the left or right fringe of the window. 2198 2199@item left-margin 2200@itemx right-margin 2201The coordinates are in the left or right margin of the window. 2202 2203@item nil 2204The coordinates are not in any part of @var{window}. 2205@end table 2206 2207The function @code{coordinates-in-window-p} does not require a frame as 2208argument because it always uses the frame that @var{window} is on. 2209@end defun 2210 2211@node Window Tree 2212@section The Window Tree 2213@cindex window tree 2214 2215 A @dfn{window tree} specifies the layout, size, and relationship 2216between all windows in one frame. 2217 2218@defun window-tree &optional frame 2219This function returns the window tree for frame @var{frame}. 2220If @var{frame} is omitted, the selected frame is used. 2221 2222The return value is a list of the form @code{(@var{root} @var{mini})}, 2223where @var{root} represents the window tree of the frame's 2224root window, and @var{mini} is the frame's minibuffer window. 2225 2226If the root window is not split, @var{root} is the root window itself. 2227Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} 2228@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, 2229and @code{t} for a vertical split, @var{edges} gives the combined size and 2230position of the subwindows in the split, and the rest of the elements 2231are the subwindows in the split. Each of the subwindows may again be 2232a window or a list representing a window split, and so on. The 2233@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} 2234similar to the value returned by @code{window-edges}. 2235@end defun 2236 2237@node Window Configurations 2238@section Window Configurations 2239@cindex window configurations 2240@cindex saving window information 2241 2242 A @dfn{window configuration} records the entire layout of one 2243frame---all windows, their sizes, which buffers they contain, what 2244part of each buffer is displayed, and the values of point and the 2245mark; also their fringes, margins, and scroll bar settings. It also 2246includes the values of @code{window-min-height}, 2247@code{window-min-width} and @code{minibuffer-scroll-window}. An 2248exception is made for point in the selected window for the current 2249buffer; its value is not saved in the window configuration. 2250 2251 You can bring back an entire previous layout by restoring a window 2252configuration previously saved. If you want to record all frames 2253instead of just one, use a frame configuration instead of a window 2254configuration. @xref{Frame Configurations}. 2255 2256@defun current-window-configuration &optional frame 2257This function returns a new object representing @var{frame}'s current 2258window configuration. If @var{frame} is omitted, the selected frame 2259is used. 2260@end defun 2261 2262@defun set-window-configuration configuration 2263This function restores the configuration of windows and buffers as 2264specified by @var{configuration}, for the frame that @var{configuration} 2265was created for. 2266 2267The argument @var{configuration} must be a value that was previously 2268returned by @code{current-window-configuration}. This configuration is 2269restored in the frame from which @var{configuration} was made, whether 2270that frame is selected or not. This always counts as a window size 2271change and triggers execution of the @code{window-size-change-functions} 2272(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't 2273know how to tell whether the new configuration actually differs from the 2274old one. 2275 2276If the frame which @var{configuration} was saved from is dead, all this 2277function does is restore the three variables @code{window-min-height}, 2278@code{window-min-width} and @code{minibuffer-scroll-window}. In this 2279case, the function returns @code{nil}. Otherwise, it returns @code{t}. 2280 2281Here is a way of using this function to get the same effect 2282as @code{save-window-excursion}: 2283 2284@example 2285@group 2286(let ((config (current-window-configuration))) 2287 (unwind-protect 2288 (progn (split-window-vertically nil) 2289 @dots{}) 2290 (set-window-configuration config))) 2291@end group 2292@end example 2293@end defun 2294 2295@defspec save-window-excursion forms@dots{} 2296This special form records the window configuration, executes @var{forms} 2297in sequence, then restores the earlier window configuration. The window 2298configuration includes, for each window, the value of point and the 2299portion of the buffer that is visible. It also includes the choice of 2300selected window. However, it does not include the value of point in 2301the current buffer; use @code{save-excursion} also, if you wish to 2302preserve that. 2303 2304Don't use this construct when @code{save-selected-window} is sufficient. 2305 2306Exit from @code{save-window-excursion} always triggers execution of the 2307@code{window-size-change-functions}. (It doesn't know how to tell 2308whether the restored configuration actually differs from the one in 2309effect at the end of the @var{forms}.) 2310 2311The return value is the value of the final form in @var{forms}. 2312For example: 2313 2314@example 2315@group 2316(split-window) 2317 @result{} #<window 25 on control.texi> 2318@end group 2319@group 2320(setq w (selected-window)) 2321 @result{} #<window 19 on control.texi> 2322@end group 2323@group 2324(save-window-excursion 2325 (delete-other-windows w) 2326 (switch-to-buffer "foo") 2327 'do-something) 2328 @result{} do-something 2329 ;; @r{The screen is now split again.} 2330@end group 2331@end example 2332@end defspec 2333 2334@defun window-configuration-p object 2335This function returns @code{t} if @var{object} is a window configuration. 2336@end defun 2337 2338@defun compare-window-configurations config1 config2 2339This function compares two window configurations as regards the 2340structure of windows, but ignores the values of point and mark and the 2341saved scrolling positions---it can return @code{t} even if those 2342aspects differ. 2343 2344The function @code{equal} can also compare two window configurations; it 2345regards configurations as unequal if they differ in any respect, even a 2346saved point or mark. 2347@end defun 2348 2349@defun window-configuration-frame config 2350This function returns the frame for which the window configuration 2351@var{config} was made. 2352@end defun 2353 2354 Other primitives to look inside of window configurations would make 2355sense, but are not implemented because we did not need them. See the 2356file @file{winner.el} for some more operations on windows 2357configurations. 2358 2359@node Window Hooks 2360@section Hooks for Window Scrolling and Changes 2361@cindex hooks for window operations 2362 2363This section describes how a Lisp program can take action whenever a 2364window displays a different part of its buffer or a different buffer. 2365There are three actions that can change this: scrolling the window, 2366switching buffers in the window, and changing the size of the window. 2367The first two actions run @code{window-scroll-functions}; the last runs 2368@code{window-size-change-functions}. 2369 2370@defvar window-scroll-functions 2371This variable holds a list of functions that Emacs should call before 2372redisplaying a window with scrolling. It is not a normal hook, because 2373each function is called with two arguments: the window, and its new 2374display-start position. 2375 2376Displaying a different buffer in the window also runs these functions. 2377 2378These functions must be careful in using @code{window-end} 2379(@pxref{Window Start}); if you need an up-to-date value, you must use 2380the @var{update} argument to ensure you get it. 2381 2382@strong{Warning:} don't use this feature to alter the way the window 2383is scrolled. It's not designed for that, and such use probably won't 2384work. 2385@end defvar 2386 2387@defvar window-size-change-functions 2388This variable holds a list of functions to be called if the size of any 2389window changes for any reason. The functions are called just once per 2390redisplay, and just once for each frame on which size changes have 2391occurred. 2392 2393Each function receives the frame as its sole argument. There is no 2394direct way to find out which windows on that frame have changed size, or 2395precisely how. However, if a size-change function records, at each 2396call, the existing windows and their sizes, it can also compare the 2397present sizes and the previous sizes. 2398 2399Creating or deleting windows counts as a size change, and therefore 2400causes these functions to be called. Changing the frame size also 2401counts, because it changes the sizes of the existing windows. 2402 2403It is not a good idea to use @code{save-window-excursion} (@pxref{Window 2404Configurations}) in these functions, because that always counts as a 2405size change, and it would cause these functions to be called over and 2406over. In most cases, @code{save-selected-window} (@pxref{Selecting 2407Windows}) is what you need here. 2408@end defvar 2409 2410@defvar redisplay-end-trigger-functions 2411This abnormal hook is run whenever redisplay in a window uses text that 2412extends past a specified end trigger position. You set the end trigger 2413position with the function @code{set-window-redisplay-end-trigger}. The 2414functions are called with two arguments: the window, and the end trigger 2415position. Storing @code{nil} for the end trigger position turns off the 2416feature, and the trigger value is automatically reset to @code{nil} just 2417after the hook is run. 2418@end defvar 2419 2420@defun set-window-redisplay-end-trigger window position 2421This function sets @var{window}'s end trigger position at 2422@var{position}. 2423@end defun 2424 2425@defun window-redisplay-end-trigger &optional window 2426This function returns @var{window}'s current end trigger position. 2427If @var{window} is @code{nil} or omitted, it uses the selected window. 2428@end defun 2429 2430@defvar window-configuration-change-hook 2431A normal hook that is run every time you change the window configuration 2432of an existing frame. This includes splitting or deleting windows, 2433changing the sizes of windows, or displaying a different buffer in a 2434window. The frame whose window configuration has changed is the 2435selected frame when this hook runs. 2436@end defvar 2437 2438@ignore 2439 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 2440@end ignore 2441