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