| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Emacs Lisp Reference Manual. |
| 3 | @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 |
| 4 | @c Free Software Foundation, Inc. |
| 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 the functions and variables related to Emacs |
| 11 | windows. @xref{Frames}, for how windows are assigned an area of screen |
| 12 | available for Emacs to use. @xref{Display}, for information on how text |
| 13 | is displayed in windows. |
| 14 | |
| 15 | @menu |
| 16 | * Basic Windows:: Basic information on using windows. |
| 17 | * Windows and Frames:: Relating windows to the frame they appear on. |
| 18 | * Window Sizes:: Accessing a window's size. |
| 19 | * Resizing Windows:: Changing the sizes of windows. |
| 20 | * Splitting Windows:: Splitting one window into two windows. |
| 21 | * Deleting Windows:: Deleting a window gives its space to other windows. |
| 22 | * Selecting Windows:: The selected window is the one that you edit in. |
| 23 | * Cyclic Window Ordering:: Moving around the existing windows. |
| 24 | * Buffers and Windows:: Each window displays the contents of a buffer. |
| 25 | * Switching Buffers:: Higher-level functions for switching to a buffer. |
| 26 | * Choosing Window:: How to choose a window for displaying a buffer. |
| 27 | * Display Action Functions:: Subroutines for @code{display-buffer}. |
| 28 | * Choosing Window Options:: Extra options affecting how buffers are displayed. |
| 29 | * Window History:: Each window remembers the buffers displayed in it. |
| 30 | * Dedicated Windows:: How to avoid displaying another buffer in |
| 31 | a specific window. |
| 32 | * Quitting Windows:: How to restore the state prior to displaying a |
| 33 | buffer. |
| 34 | * Window Point:: Each window has its own location of point. |
| 35 | * Window Start and End:: Buffer positions indicating which text is |
| 36 | on-screen in a window. |
| 37 | * Textual Scrolling:: Moving text up and down through the window. |
| 38 | * Vertical Scrolling:: Moving the contents up and down on the window. |
| 39 | * Horizontal Scrolling:: Moving the contents sideways on the window. |
| 40 | * Coordinates and Windows:: Converting coordinates to windows. |
| 41 | * Window Configurations:: Saving and restoring the state of the screen. |
| 42 | * Window Parameters:: Associating additional information with windows. |
| 43 | * Window Hooks:: Hooks for scrolling, window size changes, |
| 44 | redisplay going past a certain point, |
| 45 | or window configuration changes. |
| 46 | @end menu |
| 47 | |
| 48 | |
| 49 | @node Basic Windows |
| 50 | @section Basic Concepts of Emacs Windows |
| 51 | @cindex window |
| 52 | |
| 53 | A @dfn{window} is a area of the screen which is used to display a |
| 54 | buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a |
| 55 | special Lisp object type. |
| 56 | |
| 57 | @cindex multiple windows |
| 58 | Windows are grouped into frames (@pxref{Frames}). Each frame |
| 59 | contains at least one window; the user can subdivide it into multiple, |
| 60 | non-overlapping windows to view several buffers at once. Lisp |
| 61 | programs can use multiple windows for a variety of purposes. In |
| 62 | Rmail, for example, you can view a summary of message titles in one |
| 63 | window, and the contents of the selected message in another window. |
| 64 | |
| 65 | @cindex terminal screen |
| 66 | @cindex screen of terminal |
| 67 | Emacs uses the word ``window'' with a different meaning than in |
| 68 | graphical desktop environments and window systems, such as the X |
| 69 | Window System. When Emacs is run on X, each of its graphical X |
| 70 | windows is an Emacs frame (containing one or more Emacs windows). |
| 71 | When Emacs is run on a text-only terminal, the frame fills the entire |
| 72 | terminal screen. |
| 73 | |
| 74 | @cindex tiled windows |
| 75 | Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap |
| 76 | within the area of the frame. When a window is created, resized, or |
| 77 | deleted, the change in window space is taken from or given to the |
| 78 | adjacent windows, so that the total area of the frame is unchanged. |
| 79 | |
| 80 | @cindex live windows |
| 81 | @cindex internal windows |
| 82 | A @dfn{live window} is one that is actually displaying a buffer in a |
| 83 | frame. Such a window can be @dfn{deleted}, i.e. removed from the |
| 84 | frame (@pxref{Deleting Windows}); then it is no longer live, but the |
| 85 | Lisp object representing it might be still referenced from other Lisp |
| 86 | objects. A deleted window may be brought back to life by restoring a |
| 87 | saved window configuration (@pxref{Window Configurations}). |
| 88 | |
| 89 | @defun windowp object |
| 90 | This function returns @code{t} if @var{object} is a window (whether or |
| 91 | not it is live). Otherwise, it returns @code{nil}. |
| 92 | @end defun |
| 93 | |
| 94 | @defun window-live-p object |
| 95 | This function returns @code{t} if @var{object} is a live window and |
| 96 | @code{nil} otherwise. A live window is one that displays a buffer. |
| 97 | @end defun |
| 98 | |
| 99 | The windows in each frame are organized into a @dfn{window tree}. |
| 100 | @xref{Windows and Frames}. The leaf nodes of each window tree are |
| 101 | live windows---the ones actually displaying buffers. The internal |
| 102 | nodes of the window tree are internal windows, which are not live. |
| 103 | You can distinguish internal windows from deleted windows with |
| 104 | @code{window-valid-p}. |
| 105 | |
| 106 | @defun window-valid-p object |
| 107 | This function returns @code{t} if @var{object} is a live window, or an |
| 108 | internal window in a window tree. Otherwise, it returns @code{nil}, |
| 109 | including for the case where @var{object} is a deleted window. |
| 110 | @end defun |
| 111 | |
| 112 | @cindex selected window |
| 113 | @cindex window selected within a frame |
| 114 | In each frame, at any time, exactly one Emacs window is designated |
| 115 | as @dfn{selected within the frame}. For the selected frame, that |
| 116 | window is called the @dfn{selected window}---the one in which most |
| 117 | editing takes place, and in which the cursor for selected windows |
| 118 | appears (@pxref{Cursor Parameters}). The selected window's buffer is |
| 119 | usually also the current buffer, except when @code{set-buffer} has |
| 120 | been used (@pxref{Current Buffer}). As for non-selected frames, the |
| 121 | window selected within the frame becomes the selected window if the |
| 122 | frame is ever selected. @xref{Selecting Windows}. |
| 123 | |
| 124 | @defun selected-window |
| 125 | This function returns the selected window (which is always a live |
| 126 | window). |
| 127 | @end defun |
| 128 | |
| 129 | @node Windows and Frames |
| 130 | @section Windows and Frames |
| 131 | |
| 132 | Each window belongs to exactly one frame (@pxref{Frames}). |
| 133 | |
| 134 | @defun window-frame window |
| 135 | This function returns the frame that the window @var{window} belongs |
| 136 | to. If @var{window} is @code{nil}, it defaults to the selected |
| 137 | window. |
| 138 | @end defun |
| 139 | |
| 140 | @defun window-list &optional frame minibuffer window |
| 141 | This function returns a list of live windows belonging to the frame |
| 142 | @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to |
| 143 | the selected frame. |
| 144 | |
| 145 | The optional argument @var{minibuffer} specifies whether to include |
| 146 | the minibuffer window in the returned list. If @var{minibuffer} is |
| 147 | @code{t}, the minibuffer window is included. If @var{minibuffer} is |
| 148 | @code{nil} or omitted, the minibuffer window is included only if it is |
| 149 | active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the |
| 150 | minibuffer window is never included. |
| 151 | |
| 152 | The optional argument @var{window}, if non-@code{nil}, should be a live |
| 153 | window on the specified frame; then @var{window} will be the first |
| 154 | element in the returned list. If @var{window} is omitted or @code{nil}, |
| 155 | the window selected within the frame is the first element. |
| 156 | @end defun |
| 157 | |
| 158 | @cindex window tree |
| 159 | @cindex root window |
| 160 | Windows in the same frame are organized into a @dfn{window tree}, |
| 161 | whose leaf nodes are the live windows. The internal nodes of a window |
| 162 | tree are not live; they exist for the purpose of organizing the |
| 163 | relationships between live windows. The root node of a window tree is |
| 164 | called the @dfn{root window}. It can be either a live window (if the |
| 165 | frame has just one window), or an internal window. |
| 166 | |
| 167 | A minibuffer window (@pxref{Minibuffer Windows}) is not part of its |
| 168 | frame's window tree unless the frame is a minibuffer-only frame. |
| 169 | Nonetheless, most of the functions in this section accept the |
| 170 | minibuffer window as an argument. Also, the function |
| 171 | @code{window-tree} described at the end of this section lists the |
| 172 | minibuffer window alongside the actual window tree. |
| 173 | |
| 174 | @defun frame-root-window &optional frame-or-window |
| 175 | This function returns the root window for @var{frame-or-window}. The |
| 176 | argument @var{frame-or-window} should be either a window or a frame; |
| 177 | if omitted or @code{nil}, it defaults to the selected frame. If |
| 178 | @var{frame-or-window} is a window, the return value is the root window |
| 179 | of that window's frame. |
| 180 | @end defun |
| 181 | |
| 182 | @cindex parent window |
| 183 | @cindex child window |
| 184 | @cindex sibling window |
| 185 | When a window is split, there are two live windows where previously |
| 186 | there was one. One of these is represented by the same Lisp window |
| 187 | object as the original window, and the other is represented by a |
| 188 | newly-created Lisp window object. Both of these live windows become |
| 189 | leaf nodes of the window tree, as @dfn{child windows} of a single |
| 190 | internal window. If necessary, Emacs automatically creates this |
| 191 | internal window, which is also called the @dfn{parent window}, and |
| 192 | assigns it to the appropriate position in the window tree. A set of |
| 193 | windows that share the same parent are called @dfn{siblings}. |
| 194 | |
| 195 | @cindex parent window |
| 196 | @defun window-parent &optional window |
| 197 | This function returns the parent window of @var{window}. If |
| 198 | @var{window} is omitted or @code{nil}, it defaults to the selected |
| 199 | window. The return value is @code{nil} if @var{window} has no parent |
| 200 | (i.e. it is a minibuffer window or the root window of its frame). |
| 201 | @end defun |
| 202 | |
| 203 | Each internal window always has at least two child windows. If this |
| 204 | number falls to one as a result of window deletion, Emacs |
| 205 | automatically deletes the internal window, and its sole remaining |
| 206 | child window takes its place in the window tree. |
| 207 | |
| 208 | Each child window can be either a live window, or an internal window |
| 209 | (which in turn would have its own child windows). Therefore, each |
| 210 | internal window can be thought of as occupying a certain rectangular |
| 211 | @dfn{screen area}---the union of the areas occupied by the live |
| 212 | windows that are ultimately descended from it. |
| 213 | |
| 214 | @cindex window combination |
| 215 | @cindex vertical combination |
| 216 | @cindex horizontal combination |
| 217 | For each internal window, the screen areas of the immediate children |
| 218 | are arranged either vertically or horizontally (never both). If the |
| 219 | child windows are arranged one above the other, they are said to form |
| 220 | a @dfn{vertical combination}; if they are arranged side by side, they |
| 221 | are said to form a @dfn{horizontal combination}. Consider the |
| 222 | following example: |
| 223 | |
| 224 | @smallexample |
| 225 | @group |
| 226 | ______________________________________ |
| 227 | | ______ ____________________________ | |
| 228 | || || __________________________ || |
| 229 | || ||| ||| |
| 230 | || ||| ||| |
| 231 | || ||| ||| |
| 232 | || |||____________W4____________||| |
| 233 | || || __________________________ || |
| 234 | || ||| ||| |
| 235 | || ||| ||| |
| 236 | || |||____________W5____________||| |
| 237 | ||__W2__||_____________W3_____________ | |
| 238 | |__________________W1__________________| |
| 239 | |
| 240 | @end group |
| 241 | @end smallexample |
| 242 | |
| 243 | @noindent |
| 244 | The root window of this frame is an internal window, @code{W1}. Its |
| 245 | child windows form a horizontal combination, consisting of the live |
| 246 | window @code{W2} and the internal window @code{W3}. The child windows |
| 247 | of @code{W3} form a vertical combination, consisting of the live |
| 248 | windows @code{W4} and @code{W5}. Hence, the live windows in this |
| 249 | window tree are @code{W2} @code{W4}, and @code{W5}. |
| 250 | |
| 251 | The following functions can be used to retrieve a child window of an |
| 252 | internal window, and the siblings of a child window. |
| 253 | |
| 254 | @defun window-top-child window |
| 255 | This function returns the topmost child window of @var{window}, if |
| 256 | @var{window} is an internal window whose children form a vertical |
| 257 | combination. For any other type of window, the return value is |
| 258 | @code{nil}. |
| 259 | @end defun |
| 260 | |
| 261 | @defun window-left-child window |
| 262 | This function returns the leftmost child window of @var{window}, if |
| 263 | @var{window} is an internal window whose children form a horizontal |
| 264 | combination. For any other type of window, the return value is |
| 265 | @code{nil}. |
| 266 | @end defun |
| 267 | |
| 268 | @defun window-child window |
| 269 | This function returns the first child window of the internal window |
| 270 | @var{window}---the topmost child window for a vertical combination, or |
| 271 | the leftmost child window for a horizontal combination. If |
| 272 | @var{window} is a live window, the return value is @code{nil}. |
| 273 | @end defun |
| 274 | |
| 275 | @defun window-combined-p &optional window horizontal |
| 276 | This function returns a non-@code{nil} value if and only if |
| 277 | @var{window} is part of a vertical combination. If @var{window} is |
| 278 | omitted or @code{nil}, it defaults to the selected one. |
| 279 | |
| 280 | If the optional argument @var{horizontal} is non-@code{nil}, this |
| 281 | means to return non-@code{nil} if and only if @var{window} is part of |
| 282 | a horizontal combination. |
| 283 | @end defun |
| 284 | |
| 285 | @defun window-next-sibling &optional window |
| 286 | This function returns the next sibling of the window @var{window}. If |
| 287 | omitted or @code{nil}, @var{window} defaults to the selected window. |
| 288 | The return value is @code{nil} if @var{window} is the last child of |
| 289 | its parent. |
| 290 | @end defun |
| 291 | |
| 292 | @defun window-prev-sibling &optional window |
| 293 | This function returns the previous sibling of the window @var{window}. |
| 294 | If omitted or @code{nil}, @var{window} defaults to the selected |
| 295 | window. The return value is @code{nil} if @var{window} is the first |
| 296 | child of its parent. |
| 297 | @end defun |
| 298 | |
| 299 | The functions @code{window-next-sibling} and |
| 300 | @code{window-prev-sibling} should not be confused with the functions |
| 301 | @code{next-window} and @code{previous-window} which respectively |
| 302 | return the next and previous window in the cyclic ordering of windows |
| 303 | (@pxref{Cyclic Window Ordering}). |
| 304 | |
| 305 | You can use the following functions to find the first live window on |
| 306 | a frame, and to retrieve the entire window tree of a frame: |
| 307 | |
| 308 | @defun frame-first-window &optional frame-or-window |
| 309 | This function returns the live window at the upper left corner of the |
| 310 | frame specified by @var{frame-or-window}. The argument |
| 311 | @var{frame-or-window} must denote a window or a live frame and defaults |
| 312 | to the selected frame. If @var{frame-or-window} specifies a window, |
| 313 | this function returns the first window on that window's frame. Under |
| 314 | the assumption that the frame from our canonical example is selected |
| 315 | @code{(frame-first-window)} returns @code{W2}. |
| 316 | @end defun |
| 317 | |
| 318 | @defun window-tree &optional frame |
| 319 | This function returns a list representing the window tree for frame |
| 320 | @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to |
| 321 | the selected frame. |
| 322 | |
| 323 | The return value is a list of the form @code{(@var{root} @var{mini})}, |
| 324 | where @var{root} represents the window tree of the frame's root |
| 325 | window, and @var{mini} is the frame's minibuffer window. |
| 326 | |
| 327 | If the root window is live, @var{root} is that window itself. |
| 328 | Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} |
| 329 | @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal |
| 330 | combination and @code{t} for a vertical combination, @var{edges} gives |
| 331 | the size and position of the combination, and the remaining elements |
| 332 | are the child windows. Each child window may again be a window object |
| 333 | (for a live window) or a list with the same format as above (for an |
| 334 | internal window). The @var{edges} element is a list @code{(@var{left} |
| 335 | @var{top} @var{right} @var{bottom})}, similar to the value returned by |
| 336 | @code{window-edges} (@pxref{Coordinates and Windows}). |
| 337 | @end defun |
| 338 | |
| 339 | @node Window Sizes |
| 340 | @section Window Sizes |
| 341 | @cindex window size |
| 342 | @cindex size of window |
| 343 | |
| 344 | The following schematic shows the structure of a live window: |
| 345 | |
| 346 | @smallexample |
| 347 | @group |
| 348 | _________________________________________ |
| 349 | ^ |______________ Header Line_______________| |
| 350 | | |LS|LF|LM| |RM|RF|RS| ^ |
| 351 | | | | | | | | | | | |
| 352 | Window | | | | Text Area | | | | Window |
| 353 | Total | | | | (Window Body) | | | | Body |
| 354 | Height | | | | | | | | Height |
| 355 | | | | | |<- Window Body Width ->| | | | | |
| 356 | | |__|__|__|_______________________|__|__|__| v |
| 357 | v |_______________ Mode Line _______________| |
| 358 | |
| 359 | <----------- Window Total Width --------> |
| 360 | |
| 361 | @end group |
| 362 | @end smallexample |
| 363 | |
| 364 | @cindex window body |
| 365 | @cindex text area of a window |
| 366 | @cindex body of a window |
| 367 | At the center of the window is the @dfn{text area}, or @dfn{body}, |
| 368 | where the buffer text is displayed. On each side of the text area is |
| 369 | a series of vertical areas; from innermost to outermost, these are the |
| 370 | left and right margins, denoted by LM and RM in the schematic |
| 371 | (@pxref{Display Margins}); the left and right fringes, denoted by LF |
| 372 | and RF (@pxref{Fringes}); and the left or right scroll bar, only one of |
| 373 | which is present at any time, denoted by LS and RS (@pxref{Scroll |
| 374 | Bars}). At the top of the window is an optional header line |
| 375 | (@pxref{Header Lines}), and at the bottom of the window is the mode |
| 376 | line (@pxref{Mode Line Format}). |
| 377 | |
| 378 | Emacs provides several functions for finding the height and width of |
| 379 | a window. Except where noted, Emacs reports window heights and widths |
| 380 | as integer numbers of lines and columns respectively. On a graphical |
| 381 | display, each ``line'' and ``column'' actually corresponds to the |
| 382 | height and width of a ``default'' character specified by the frame's |
| 383 | default font. Thus, if a window is displaying text with a different |
| 384 | font or size, the reported height and width for that window may differ |
| 385 | from the actual number of text lines or columns displayed within it. |
| 386 | |
| 387 | @cindex window height |
| 388 | @cindex height of a window |
| 389 | @cindex total height of a window |
| 390 | @cindex window width |
| 391 | @cindex width of a window |
| 392 | @cindex total width of a window |
| 393 | The @dfn{total height} of a window is the distance between the top |
| 394 | and bottom of the window, including the header line (if one exists) |
| 395 | and the mode line. The @dfn{total width} of a window is the distance |
| 396 | between the left and right edges of the mode line. Note that the |
| 397 | height of a frame is not the same as the height of its windows, since |
| 398 | a frame may also contain an echo area, menu bar, and tool bar |
| 399 | (@pxref{Size and Position}). |
| 400 | |
| 401 | @defun window-total-height &optional window |
| 402 | This function returns the total height, in lines, of the window |
| 403 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 404 | to the selected window. If @var{window} is an internal window, the |
| 405 | return value is the total height occupied by its descendant windows. |
| 406 | @end defun |
| 407 | |
| 408 | @defun window-total-width &optional window |
| 409 | This function returns the total width, in columns, of the window |
| 410 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 411 | to the selected window. If @var{window} is internal, the return value |
| 412 | is the total width occupied by its descendant windows. |
| 413 | @end defun |
| 414 | |
| 415 | @defun window-total-size &optional window horizontal |
| 416 | This function returns either the total height or width of the window |
| 417 | @var{window}. If @var{horizontal} is omitted or @code{nil}, this is |
| 418 | equivalent to calling @code{window-total-height} for @var{window}; |
| 419 | otherwise it is equivalent to calling @code{window-total-width} for |
| 420 | @var{window}. |
| 421 | @end defun |
| 422 | |
| 423 | @cindex full-width window |
| 424 | @cindex full-height window |
| 425 | The following functions can be used to determine whether a given |
| 426 | window has any adjacent windows. |
| 427 | |
| 428 | @defun window-full-height-p &optional window |
| 429 | This function returns non-@code{nil} if @var{window} has no other |
| 430 | window above or below it in its frame, i.e. its total height equals |
| 431 | the total height of the root window on that frame. If @var{window} is |
| 432 | omitted or @code{nil}, it defaults to the selected window. |
| 433 | @end defun |
| 434 | |
| 435 | @defun window-full-width-p &optional window |
| 436 | This function returns non-@code{nil} if @var{window} has no other |
| 437 | window to the left or right in its frame, i.e. its total width equals |
| 438 | that of the root window on that frame. If @var{window} is omitted or |
| 439 | @code{nil}, it defaults to the selected window. |
| 440 | @end defun |
| 441 | |
| 442 | @cindex window body height |
| 443 | @cindex body height of a window |
| 444 | @cindex window body width |
| 445 | @cindex body width of a window |
| 446 | @cindex body size of a window |
| 447 | @cindex window body size |
| 448 | The @dfn{body height} of a window is the height of its text area, |
| 449 | which does not include the mode or header line. Similarly, the |
| 450 | @dfn{body width} is the width of the text area, which does not include |
| 451 | the scroll bar, fringes, or margins. |
| 452 | |
| 453 | @defun window-body-height &optional window |
| 454 | This function returns the body height, in lines, of the window |
| 455 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 456 | to the selected window; otherwise it must be a live window. |
| 457 | |
| 458 | If there is a partially-visible line at the bottom of the text area, |
| 459 | that counts as a whole line; to exclude such a partially-visible line, |
| 460 | use @code{window-text-height}, below. |
| 461 | @end defun |
| 462 | |
| 463 | @defun window-body-width &optional window |
| 464 | This function returns the body width, in columns, of the window |
| 465 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 466 | to the selected window; otherwise it must be a live window. |
| 467 | @end defun |
| 468 | |
| 469 | @defun window-body-size &optional window horizontal |
| 470 | This function returns the body height or body width of @var{window}. |
| 471 | If @var{horizontal} is omitted or @code{nil}, it is equivalent to |
| 472 | calling @code{window-body-height} for @var{window}; otherwise it is |
| 473 | equivalent to calling @code{window-body-width}. |
| 474 | @end defun |
| 475 | |
| 476 | @defun window-text-height &optional window |
| 477 | This function is like @code{window-body-height}, except that any |
| 478 | partially-visible line at the bottom of the text area is not counted. |
| 479 | @end defun |
| 480 | |
| 481 | For compatibility with previous versions of Emacs, |
| 482 | @code{window-height} is an alias for @code{window-body-height}, and |
| 483 | @code{window-width} is an alias for @code{window-body-width}. These |
| 484 | aliases are considered obsolete and will be removed in the future. |
| 485 | |
| 486 | @cindex fixed-size window |
| 487 | Commands that change the size of windows (@pxref{Resizing Windows}), |
| 488 | or split them (@pxref{Splitting Windows}), obey the variables |
| 489 | @code{window-min-height} and @code{window-min-width}, which specify |
| 490 | the smallest allowable window height and width. @xref{Change |
| 491 | Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs |
| 492 | Manual}. They also obey the variable @code{window-size-fixed}, with |
| 493 | which a window can be @dfn{fixed} in size: |
| 494 | |
| 495 | @defvar window-size-fixed |
| 496 | If this buffer-local variable is non-@code{nil}, the size of any |
| 497 | window displaying the buffer cannot normally be changed. Deleting a |
| 498 | window or changing the frame's size may still change its size, if |
| 499 | there is no choice. |
| 500 | |
| 501 | If the value is @code{height}, then only the window's height is fixed; |
| 502 | if the value is @code{width}, then only the window's width is fixed. |
| 503 | Any other non-@code{nil} value fixes both the width and the height. |
| 504 | @end defvar |
| 505 | |
| 506 | @defun window-size-fixed-p &optional window horizontal |
| 507 | This function returns a non-@code{nil} value if @var{window}'s height |
| 508 | is fixed. If @var{window} is omitted or @code{nil}, it defaults to |
| 509 | the selected window. If the optional argument @var{horizontal} is |
| 510 | non-@code{nil}, the return value is non-@code{nil} if @var{window}'s |
| 511 | width is fixed. |
| 512 | |
| 513 | A @code{nil} return value does not necessarily mean that @var{window} |
| 514 | can be resized in the desired direction. To determine that, use the |
| 515 | function @code{window-resizable}. @xref{Resizing Windows}. |
| 516 | @end defun |
| 517 | |
| 518 | @xref{Coordinates and Windows}, for more functions that report the |
| 519 | positions of various parts of a window relative to the frame, from |
| 520 | which you can calculate its size. In particular, you can use the |
| 521 | functions @code{window-pixel-edges} and |
| 522 | @code{window-inside-pixel-edges} to find the size in pixels, for |
| 523 | graphical displays. |
| 524 | |
| 525 | @node Resizing Windows |
| 526 | @section Resizing Windows |
| 527 | @cindex window resizing |
| 528 | @cindex resize window |
| 529 | @cindex changing window size |
| 530 | @cindex window size, changing |
| 531 | |
| 532 | This section describes functions for resizing a window without |
| 533 | changing the size of its frame. Because live windows do not overlap, |
| 534 | these functions are meaningful only on frames that contain two or more |
| 535 | windows: resizing a window also changes the size of a neighboring |
| 536 | window. If there is just one window on a frame, its size cannot be |
| 537 | changed except by resizing the frame (@pxref{Size and Position}). |
| 538 | |
| 539 | Except where noted, these functions also accept internal windows as |
| 540 | arguments. Resizing an internal window causes its child windows to be |
| 541 | resized to fit the same space. |
| 542 | |
| 543 | @defun window-resizable window delta &optional horizontal ignore |
| 544 | This function returns @var{delta} if the size of @var{window} can be |
| 545 | changed vertically by @var{delta} lines. If the optional argument |
| 546 | @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if |
| 547 | @var{window} can be resized horizontally by @var{delta} columns. It |
| 548 | does not actually change the window size. |
| 549 | |
| 550 | If @var{window} is @code{nil}, it defaults to the selected window. |
| 551 | |
| 552 | A positive value of @var{delta} means to check whether the window can be |
| 553 | enlarged by that number of lines or columns; a negative value of |
| 554 | @var{delta} means to check whether the window can be shrunk by that many |
| 555 | lines or columns. If @var{delta} is non-zero, a return value of 0 means |
| 556 | that the window cannot be resized. |
| 557 | |
| 558 | Normally, the variables @code{window-min-height} and |
| 559 | @code{window-min-width} specify the smallest allowable window size. |
| 560 | @xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU |
| 561 | Emacs Manual}. However, if the optional argument @var{ignore} is |
| 562 | non-@code{nil}, this function ignores @code{window-min-height} and |
| 563 | @code{window-min-width}, as well as @code{window-size-fixed}. |
| 564 | Instead, it considers the minimum-height window to be one consisting |
| 565 | of a header (if any), a mode line, plus a text area one line tall; and |
| 566 | a minimum-width window as one consisting of fringes, margins, and |
| 567 | scroll bar (if any), plus a text area two columns wide. |
| 568 | @end defun |
| 569 | |
| 570 | @defun window-resize window delta &optional horizontal ignore |
| 571 | This function resizes @var{window} by @var{delta} increments. If |
| 572 | @var{horizontal} is @code{nil}, it changes the height by @var{delta} |
| 573 | lines; otherwise, it changes the width by @var{delta} columns. A |
| 574 | positive @var{delta} means to enlarge the window, and a negative |
| 575 | @var{delta} means to shrink it. |
| 576 | |
| 577 | If @var{window} is @code{nil}, it defaults to the selected window. If |
| 578 | the window cannot be resized as demanded, an error is signaled. |
| 579 | |
| 580 | The optional argument @var{ignore} has the same meaning as for the |
| 581 | function @code{window-resizable} above. |
| 582 | |
| 583 | The choice of which window edges this function alters depends on the |
| 584 | values of the option @code{window-combination-resize} and the |
| 585 | combination limits of the involved windows; in some cases, it may alter |
| 586 | both edges. @xref{Splitting Windows}. To resize by moving only the |
| 587 | bottom or right edge of a window, use the function |
| 588 | @code{adjust-window-trailing-edge}, below. |
| 589 | @end defun |
| 590 | |
| 591 | @c The commands enlarge-window, enlarge-window-horizontally, |
| 592 | @c shrink-window, and shrink-window-horizontally are documented in the |
| 593 | @c Emacs manual. They are not preferred for calling from Lisp. |
| 594 | |
| 595 | @defun adjust-window-trailing-edge window delta &optional horizontal |
| 596 | This function moves @var{window}'s bottom edge by @var{delta} lines. |
| 597 | If optional argument @var{horizontal} is non-@code{nil}, it instead |
| 598 | moves the right edge by @var{delta} columns. If @var{window} is |
| 599 | @code{nil}, it defaults to the selected window. |
| 600 | |
| 601 | A positive @var{delta} moves the edge downwards or to the right; a |
| 602 | negative @var{delta} moves it upwards or to the left. If the edge |
| 603 | cannot be moved as far as specified by @var{delta}, this function |
| 604 | moves it as far as possible but does not signal a error. |
| 605 | |
| 606 | This function tries to resize windows adjacent to the edge that is |
| 607 | moved. If this is not possible for some reason (e.g. if that adjacent |
| 608 | window is fixed-size), it may resize other windows. |
| 609 | @end defun |
| 610 | |
| 611 | The following commands resize windows in more specific ways. When |
| 612 | called interactively, they act on the selected window. |
| 613 | |
| 614 | @deffn Command fit-window-to-buffer &optional window max-height min-height override |
| 615 | This command adjusts the height of @var{window} to fit the text in it. |
| 616 | It returns non-@code{nil} if it was able to resize @var{window}, and |
| 617 | @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it |
| 618 | defaults to the selected window. Otherwise, it should be a live |
| 619 | window. |
| 620 | |
| 621 | The optional argument @var{max-height}, if non-@code{nil}, specifies |
| 622 | the maximum total height that this function can give @var{window}. |
| 623 | The optional argument @var{min-height}, if no-@code{nil}, specifies |
| 624 | the minimum total height that it can give, which overrides the |
| 625 | variable @code{window-min-height}. |
| 626 | |
| 627 | If the optional argument @var{override} is non-@code{nil}, this |
| 628 | function ignores any size restrictions imposed by |
| 629 | @code{window-min-height} and @code{window-min-width}. |
| 630 | @end deffn |
| 631 | |
| 632 | @deffn Command shrink-window-if-larger-than-buffer &optional window |
| 633 | This command attempts to reduce @var{window}'s height as much as |
| 634 | possible while still showing its full buffer, but no less than |
| 635 | @code{window-min-height} lines. The return value is non-@code{nil} if |
| 636 | the window was resized, and @code{nil} otherwise. If @var{window} is |
| 637 | omitted or @code{nil}, it defaults to the selected window. Otherwise, |
| 638 | it should be a live window. |
| 639 | |
| 640 | This command does nothing if the window is already too short to |
| 641 | display all of its buffer, or if any of the buffer is scrolled |
| 642 | off-screen, or if the window is the only live window in its frame. |
| 643 | @end deffn |
| 644 | |
| 645 | @cindex balancing window sizes |
| 646 | @deffn Command balance-windows &optional window-or-frame |
| 647 | This function balances windows in a way that gives more space to |
| 648 | full-width and/or full-height windows. If @var{window-or-frame} |
| 649 | specifies a frame, it balances all windows on that frame. If |
| 650 | @var{window-or-frame} specifies a window, it balances only that window |
| 651 | and its siblings (@pxref{Windows and Frames}). |
| 652 | @end deffn |
| 653 | |
| 654 | @deffn Command balance-windows-area |
| 655 | This function attempts to give all windows on the selected frame |
| 656 | approximately the same share of the screen area. Full-width or |
| 657 | full-height windows are not given more space than other windows. |
| 658 | @end deffn |
| 659 | |
| 660 | @cindex maximizing windows |
| 661 | @deffn Command maximize-window &optional window |
| 662 | This function attempts to make @var{window} as large as possible, in |
| 663 | both dimensions, without resizing its frame or deleting other windows. |
| 664 | If @var{window} is omitted or @code{nil}, it defaults to the selected |
| 665 | window. |
| 666 | @end deffn |
| 667 | |
| 668 | @cindex minimizing windows |
| 669 | @deffn Command minimize-window &optional window |
| 670 | This function attempts to make @var{window} as small as possible, in |
| 671 | both dimensions, without deleting it or resizing its frame. If |
| 672 | @var{window} is omitted or @code{nil}, it defaults to the selected |
| 673 | window. |
| 674 | @end deffn |
| 675 | |
| 676 | |
| 677 | @node Splitting Windows |
| 678 | @section Splitting Windows |
| 679 | @cindex splitting windows |
| 680 | @cindex window splitting |
| 681 | |
| 682 | This section describes functions for creating a new window by |
| 683 | @dfn{splitting} an existing one. |
| 684 | |
| 685 | @deffn Command split-window &optional window size side |
| 686 | This function creates a new live window next to the window |
| 687 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 688 | to the selected window. That window is ``split'', and reduced in |
| 689 | size. The space is taken up by the new window, which is returned. |
| 690 | |
| 691 | The optional second argument @var{size} determines the sizes of |
| 692 | @var{window} and/or the new window. If it is omitted or @code{nil}, |
| 693 | both windows are given equal sizes; if there is an odd line, it is |
| 694 | allocated to the new window. If @var{size} is a positive number, |
| 695 | @var{window} is given @var{size} lines (or columns, depending on the |
| 696 | value of @var{side}). If @var{size} is a negative number, the new |
| 697 | window is given @minus{}@var{size} lines (or columns). |
| 698 | |
| 699 | If @var{size} is @code{nil}, this function obeys the variables |
| 700 | @code{window-min-height} and @code{window-min-width}. @xref{Change |
| 701 | Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs |
| 702 | Manual}. Thus, it signals an error if splitting would result in |
| 703 | making a window smaller than those variables specify. However, a |
| 704 | non-@code{nil} value for @var{size} causes those variables to be |
| 705 | ignored; in that case, the smallest allowable window is considered to |
| 706 | be one that has space for a text area one line tall and/or two columns |
| 707 | wide. |
| 708 | |
| 709 | The optional third argument @var{side} determines the position of the |
| 710 | new window relative to @var{window}. If it is @code{nil} or |
| 711 | @code{below}, the new window is placed below @var{window}. If it is |
| 712 | @code{above}, the new window is placed above @var{window}. In both |
| 713 | these cases, @var{size} specifies a total window height, in lines. |
| 714 | |
| 715 | If @var{side} is @code{t} or @code{right}, the new window is placed on |
| 716 | the right of @var{window}. If @var{side} is @code{left}, the new |
| 717 | window is placed on the left of @var{window}. In both these cases, |
| 718 | @var{size} specifies a total window width, in columns. |
| 719 | |
| 720 | If @var{window} is a live window, the new window inherits various |
| 721 | properties from it, including margins and scroll bars. If |
| 722 | @var{window} is an internal window, the new window inherits the |
| 723 | properties of the window selected within @var{window}'s frame. |
| 724 | |
| 725 | The behavior of this function may be altered by the window parameters |
| 726 | of @var{window}, so long as the variable |
| 727 | @code{ignore-window-parameters} is non-@code{nil}. If the value of |
| 728 | the @code{split-window} window parameter is @code{t}, this function |
| 729 | ignores all other window parameters. Otherwise, if the value of the |
| 730 | @code{split-window} window parameter is a function, that function is |
| 731 | called with the arguments @var{window}, @var{size}, and @var{side}, in |
| 732 | lieu of the usual action of @code{split-window}. Otherwise, this |
| 733 | function obeys the @code{window-atom} or @code{window-side} window |
| 734 | parameter, if any. @xref{Window Parameters}. |
| 735 | @end deffn |
| 736 | |
| 737 | As an example, here is a sequence of @code{split-window} calls that |
| 738 | yields the window configuration discussed in @ref{Windows and Frames}. |
| 739 | This example demonstrates splitting a live window as well as splitting |
| 740 | an internal window. We begin with a frame containing a single window |
| 741 | (a live root window), which we denote by @var{W4}. Calling |
| 742 | @code{(split-window W4)} yields this window configuration: |
| 743 | |
| 744 | @smallexample |
| 745 | @group |
| 746 | ______________________________________ |
| 747 | | ____________________________________ | |
| 748 | || || |
| 749 | || || |
| 750 | || || |
| 751 | ||_________________W4_________________|| |
| 752 | | ____________________________________ | |
| 753 | || || |
| 754 | || || |
| 755 | || || |
| 756 | ||_________________W5_________________|| |
| 757 | |__________________W3__________________| |
| 758 | |
| 759 | @end group |
| 760 | @end smallexample |
| 761 | |
| 762 | @noindent |
| 763 | The @code{split-window} call has created a new live window, denoted by |
| 764 | @var{W5}. It has also created a new internal window, denoted by |
| 765 | @var{W3}, which becomes the root window and the parent of both |
| 766 | @var{W4} and @var{W5}. |
| 767 | |
| 768 | Next, we call @code{(split-window W3 nil 'left)}, passing the |
| 769 | internal window @var{W3} as the argument. The result: |
| 770 | |
| 771 | @smallexample |
| 772 | @group |
| 773 | ______________________________________ |
| 774 | | ______ ____________________________ | |
| 775 | || || __________________________ || |
| 776 | || ||| ||| |
| 777 | || ||| ||| |
| 778 | || ||| ||| |
| 779 | || |||____________W4____________||| |
| 780 | || || __________________________ || |
| 781 | || ||| ||| |
| 782 | || ||| ||| |
| 783 | || |||____________W5____________||| |
| 784 | ||__W2__||_____________W3_____________ | |
| 785 | |__________________W1__________________| |
| 786 | @end group |
| 787 | @end smallexample |
| 788 | |
| 789 | @noindent |
| 790 | A new live window @var{W2} is created, to the left of the internal |
| 791 | window @var{W3}. A new internal window @var{W1} is created, becoming |
| 792 | the new root window. |
| 793 | |
| 794 | @defopt window-combination-resize |
| 795 | If this variable is @code{nil}, @code{split-window} can only split a |
| 796 | window (denoted by @var{window}) if @var{window}'s screen area is large |
| 797 | enough to accommodate both itself and the new window. |
| 798 | |
| 799 | If this variable is @code{t}, @code{split-window} tries to resize all |
| 800 | windows that are part of the same combination as @var{window}, in order |
| 801 | to accommodate the new window. In particular, this may allow |
| 802 | @code{split-window} to succeed even if @var{window} is a fixed-size |
| 803 | window or too small to ordinarily split. Furthermore, subsequently |
| 804 | resizing or deleting @var{window} may resize all other windows in its |
| 805 | combination. |
| 806 | |
| 807 | The default is @code{nil}. Other values are reserved for future use. |
| 808 | The value of this variable is ignored when |
| 809 | @code{window-combination-limit} is non-@code{nil} (see below). |
| 810 | @end defopt |
| 811 | |
| 812 | To illustrate the effect of @code{window-combination-resize}, |
| 813 | consider the following window configuration: |
| 814 | |
| 815 | @smallexample |
| 816 | @group |
| 817 | ______________________________________ |
| 818 | | ____________________________________ | |
| 819 | || || |
| 820 | || || |
| 821 | || || |
| 822 | || || |
| 823 | ||_________________W2_________________|| |
| 824 | | ____________________________________ | |
| 825 | || || |
| 826 | || || |
| 827 | || || |
| 828 | || || |
| 829 | ||_________________W3_________________|| |
| 830 | |__________________W1__________________| |
| 831 | |
| 832 | @end group |
| 833 | @end smallexample |
| 834 | |
| 835 | @noindent |
| 836 | If @code{window-combination-resize} is @code{nil}, splitting window |
| 837 | @code{W3} leaves the size of @code{W2} unchanged: |
| 838 | |
| 839 | @smallexample |
| 840 | @group |
| 841 | ______________________________________ |
| 842 | | ____________________________________ | |
| 843 | || || |
| 844 | || || |
| 845 | || || |
| 846 | || || |
| 847 | ||_________________W2_________________|| |
| 848 | | ____________________________________ | |
| 849 | || || |
| 850 | ||_________________W3_________________|| |
| 851 | | ____________________________________ | |
| 852 | || || |
| 853 | ||_________________W4_________________|| |
| 854 | |__________________W1__________________| |
| 855 | |
| 856 | @end group |
| 857 | @end smallexample |
| 858 | |
| 859 | @noindent |
| 860 | If @code{window-combination-resize} is @code{t}, splitting @code{W3} |
| 861 | instead leaves all three live windows with approximately the same |
| 862 | height: |
| 863 | |
| 864 | @smallexample |
| 865 | @group |
| 866 | ______________________________________ |
| 867 | | ____________________________________ | |
| 868 | || || |
| 869 | || || |
| 870 | ||_________________W2_________________|| |
| 871 | | ____________________________________ | |
| 872 | || || |
| 873 | || || |
| 874 | ||_________________W3_________________|| |
| 875 | | ____________________________________ | |
| 876 | || || |
| 877 | || || |
| 878 | ||_________________W4_________________|| |
| 879 | |__________________W1__________________| |
| 880 | |
| 881 | @end group |
| 882 | @end smallexample |
| 883 | |
| 884 | @defopt window-combination-limit |
| 885 | If the value of this variable is @code{t}, the @code{split-window} |
| 886 | function always creates a new internal window. If the value is |
| 887 | @code{nil}, the new live window is allowed to share the existing |
| 888 | parent window, if one exists, provided the split occurs in the same |
| 889 | direction as the existing window combination (otherwise, a new |
| 890 | internal window is created anyway). The default is @code{nil}. Other |
| 891 | values are reserved for future use. |
| 892 | |
| 893 | Thus, if the value of this variable is at all times @code{t}, then at |
| 894 | all times every window tree is a binary tree (a tree where each window |
| 895 | except the root window has exactly one sibling). |
| 896 | |
| 897 | Furthermore, @code{split-window} calls |
| 898 | @code{set-window-combination-limit} on the newly-created internal |
| 899 | window, recording the current value of this variable. This affects |
| 900 | how the window tree is rearranged when the child windows are deleted |
| 901 | (see below). |
| 902 | @end defopt |
| 903 | |
| 904 | @cindex window combination limit |
| 905 | @defun set-window-combination-limit window limit |
| 906 | This functions sets the @dfn{combination limit} of the window |
| 907 | @var{window} to @var{limit}. This value can be retrieved via the |
| 908 | function @code{window-combination-limit}. See below for its effects; |
| 909 | note that it is only meaningful for internal windows. The |
| 910 | @code{split-window} function automatically calls this function, passing |
| 911 | the value of the variable @code{window-combination-limit} as |
| 912 | @var{limit}. |
| 913 | @end defun |
| 914 | |
| 915 | @defun window-combination-limit window |
| 916 | This function returns the combination limit for @var{window}. |
| 917 | |
| 918 | The combination limit is meaningful only for an internal window. If |
| 919 | it is @code{nil}, then Emacs is allowed to automatically delete |
| 920 | @var{window}, in response to a window deletion, in order to group the |
| 921 | child windows of @var{window} with its sibling windows to form a new |
| 922 | window combination. If the combination limit is @code{t}, the child |
| 923 | windows of @var{window} are never automatically re-combined with its |
| 924 | siblings. |
| 925 | @end defun |
| 926 | |
| 927 | To illustrate the effect of @code{window-combination-limit}, |
| 928 | consider the following configuration (throughout this example, we will |
| 929 | assume that @code{window-combination-resize} is @code{nil}): |
| 930 | |
| 931 | @smallexample |
| 932 | @group |
| 933 | ______________________________________ |
| 934 | | ____________________________________ | |
| 935 | || || |
| 936 | || || |
| 937 | || || |
| 938 | || || |
| 939 | || || |
| 940 | || || |
| 941 | ||_________________W2_________________|| |
| 942 | | ____________________________________ | |
| 943 | || || |
| 944 | || || |
| 945 | ||_________________W3_________________|| |
| 946 | |__________________W1__________________| |
| 947 | |
| 948 | @end group |
| 949 | @end smallexample |
| 950 | |
| 951 | @noindent |
| 952 | If @code{window-combination-limit} is @code{nil}, splitting @code{W2} |
| 953 | into two windows, one above the other, yields |
| 954 | |
| 955 | @smallexample |
| 956 | @group |
| 957 | ______________________________________ |
| 958 | | ____________________________________ | |
| 959 | || || |
| 960 | || || |
| 961 | ||_________________W2_________________|| |
| 962 | | ____________________________________ | |
| 963 | || || |
| 964 | || || |
| 965 | ||_________________W4_________________|| |
| 966 | | ____________________________________ | |
| 967 | || || |
| 968 | || || |
| 969 | ||_________________W3_________________|| |
| 970 | |__________________W1__________________| |
| 971 | |
| 972 | @end group |
| 973 | @end smallexample |
| 974 | |
| 975 | @noindent |
| 976 | The newly-created window, @code{W4}, shares the same internal window |
| 977 | @code{W1}. If @code{W4} is resized, it is allowed to resize the other |
| 978 | live window, @code{W3}. |
| 979 | |
| 980 | If @code{window-combination-limit} is @code{t}, splitting @code{W2} |
| 981 | in the initial configuration would instead have produced this: |
| 982 | |
| 983 | @smallexample |
| 984 | @group |
| 985 | ______________________________________ |
| 986 | | ____________________________________ | |
| 987 | || __________________________________ || |
| 988 | ||| ||| |
| 989 | |||________________W2________________||| |
| 990 | || __________________________________ || |
| 991 | ||| ||| |
| 992 | |||________________W4________________||| |
| 993 | ||_________________W5_________________|| |
| 994 | | ____________________________________ | |
| 995 | || || |
| 996 | || || |
| 997 | ||_________________W3_________________|| |
| 998 | |__________________W1__________________| |
| 999 | |
| 1000 | @end group |
| 1001 | @end smallexample |
| 1002 | |
| 1003 | @noindent |
| 1004 | A new internal window @code{W5} has been created; its children are |
| 1005 | @code{W2} and the new live window @code{W4}. Now, @code{W2} is the |
| 1006 | only sibling of @code{W4}, so resizing @code{W4} will resize |
| 1007 | @code{W2}, leaving @code{W3} unaffected. |
| 1008 | |
| 1009 | For interactive use, Emacs provides two commands which always split |
| 1010 | the selected window. These call @code{split-window} internally. |
| 1011 | |
| 1012 | @deffn Command split-window-right &optional size |
| 1013 | This function splits the selected window into two side-by-side |
| 1014 | windows, putting the selected window on the left. If @var{size} is |
| 1015 | positive, the left window gets @var{size} columns; if @var{size} is |
| 1016 | negative, the right window gets @minus{}@var{size} columns. |
| 1017 | @end deffn |
| 1018 | |
| 1019 | @deffn Command split-window-below &optional size |
| 1020 | This function splits the selected window into two windows, one above |
| 1021 | the other, leaving the upper window selected. If @var{size} is |
| 1022 | positive, the upper window gets @var{size} lines; if @var{size} is |
| 1023 | negative, the lower window gets @minus{}@var{size} lines. |
| 1024 | @end deffn |
| 1025 | |
| 1026 | @defopt split-window-keep-point |
| 1027 | If the value of this variable is non-@code{nil} (the default), |
| 1028 | @code{split-window-below} behaves as described above. |
| 1029 | |
| 1030 | If it is @code{nil}, @code{split-window-below} adjusts point in each |
| 1031 | of the two windows to minimize redisplay. (This is useful on slow |
| 1032 | terminals.) It selects whichever window contains the screen line that |
| 1033 | point was previously on. Note that this only affects |
| 1034 | @code{split-window-below}, not the lower-level @code{split-window} |
| 1035 | function. |
| 1036 | @end defopt |
| 1037 | |
| 1038 | @node Deleting Windows |
| 1039 | @section Deleting Windows |
| 1040 | @cindex deleting windows |
| 1041 | |
| 1042 | @dfn{Deleting} a window removes it from the frame's window tree. If |
| 1043 | the window is a live window, it disappears from the screen. If the |
| 1044 | window is an internal window, its child windows are deleted too. |
| 1045 | |
| 1046 | Even after a window is deleted, it continues to exist as a Lisp |
| 1047 | object, until there are no more references to it. Window deletion can |
| 1048 | be reversed, by restoring a saved window configuration (@pxref{Window |
| 1049 | Configurations}). |
| 1050 | |
| 1051 | @deffn Command delete-window &optional window |
| 1052 | This function removes @var{window} from display and returns |
| 1053 | @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to |
| 1054 | the selected window. If deleting the window would leave no more |
| 1055 | windows in the window tree (e.g. if it is the only live window in the |
| 1056 | frame), an error is signaled. |
| 1057 | |
| 1058 | By default, the space taken up by @var{window} is given to one of its |
| 1059 | adjacent sibling windows, if any. However, if the variable |
| 1060 | @code{window-combination-resize} is non-@code{nil}, the space is |
| 1061 | proportionally distributed among any remaining windows in the window |
| 1062 | combination. @xref{Splitting Windows}. |
| 1063 | |
| 1064 | The behavior of this function may be altered by the window parameters |
| 1065 | of @var{window}, so long as the variable |
| 1066 | @code{ignore-window-parameters} is non-@code{nil}. If the value of |
| 1067 | the @code{delete-window} window parameter is @code{t}, this function |
| 1068 | ignores all other window parameters. Otherwise, if the value of the |
| 1069 | @code{delete-window} window parameter is a function, that function is |
| 1070 | called with the argument @var{window}, in lieu of the usual action of |
| 1071 | @code{delete-window}. Otherwise, this function obeys the |
| 1072 | @code{window-atom} or @code{window-side} window parameter, if any. |
| 1073 | @xref{Window Parameters}. |
| 1074 | @end deffn |
| 1075 | |
| 1076 | @deffn Command delete-other-windows &optional window |
| 1077 | This function makes @var{window} fill its frame, by deleting other |
| 1078 | windows as necessary. If @var{window} is omitted or @code{nil}, it |
| 1079 | defaults to the selected window. The return value is @code{nil}. |
| 1080 | |
| 1081 | The behavior of this function may be altered by the window parameters |
| 1082 | of @var{window}, so long as the variable |
| 1083 | @code{ignore-window-parameters} is non-@code{nil}. If the value of |
| 1084 | the @code{delete-other-windows} window parameter is @code{t}, this |
| 1085 | function ignores all other window parameters. Otherwise, if the value |
| 1086 | of the @code{delete-other-windows} window parameter is a function, |
| 1087 | that function is called with the argument @var{window}, in lieu of the |
| 1088 | usual action of @code{delete-other-windows}. Otherwise, this function |
| 1089 | obeys the @code{window-atom} or @code{window-side} window parameter, |
| 1090 | if any. @xref{Window Parameters}. |
| 1091 | @end deffn |
| 1092 | |
| 1093 | @deffn Command delete-windows-on &optional buffer-or-name frame |
| 1094 | This function deletes all windows showing @var{buffer-or-name}, by |
| 1095 | calling @code{delete-window} on those windows. @var{buffer-or-name} |
| 1096 | should be a buffer, or the name of a buffer; if omitted or @code{nil}, |
| 1097 | it defaults to the current buffer. If there are no windows showing |
| 1098 | the specified buffer, this function does nothing. If the specified |
| 1099 | buffer is a minibuffer, an error is signaled. |
| 1100 | |
| 1101 | If there is a dedicated window showing the buffer, and that window is |
| 1102 | the only one on its frame, this function also deletes that frame if it |
| 1103 | is not the only frame on the terminal. |
| 1104 | |
| 1105 | The optional argument @var{frame} specifies which frames to operate |
| 1106 | on: |
| 1107 | |
| 1108 | @itemize @bullet |
| 1109 | @item @code{nil} |
| 1110 | means operate on all frames. |
| 1111 | @item @code{t} |
| 1112 | means operate on the selected frame. |
| 1113 | @item @code{visible} |
| 1114 | means operate on all visible frames. |
| 1115 | @item @code{0} |
| 1116 | means operate on all visible or iconified frames. |
| 1117 | @item A frame |
| 1118 | means operate on that frame. |
| 1119 | @end itemize |
| 1120 | |
| 1121 | Note that this argument does not have the same meaning as in other |
| 1122 | functions which scan all live windows (@pxref{Cyclic Window |
| 1123 | Ordering}). Specifically, the values @code{t} and @code{nil} have the |
| 1124 | opposite of their meanings in those other functions. |
| 1125 | @end deffn |
| 1126 | |
| 1127 | @node Selecting Windows |
| 1128 | @section Selecting Windows |
| 1129 | @cindex selecting a window |
| 1130 | |
| 1131 | @defun select-window window &optional norecord |
| 1132 | This function makes @var{window} the selected window, as well as the |
| 1133 | window selected within its frame (@pxref{Basic Windows}). |
| 1134 | @var{window} must be a live window. Unless @var{window} already is the |
| 1135 | selected window, its buffer becomes the current buffer (@pxref{Buffers |
| 1136 | and Windows}). The return value is @var{window}. |
| 1137 | |
| 1138 | By default, this function also moves @var{window}'s selected buffer to |
| 1139 | the front of the buffer list (@pxref{The Buffer List}), and makes |
| 1140 | @var{window} the most recently selected window. However, if the |
| 1141 | optional argument @var{norecord} is non-@code{nil}, these additional |
| 1142 | actions are omitted. |
| 1143 | @end defun |
| 1144 | |
| 1145 | @cindex most recently selected windows |
| 1146 | The sequence of calls to @code{select-window} with a non-@code{nil} |
| 1147 | @var{norecord} argument determines an ordering of windows by their |
| 1148 | selection time. The function @code{get-lru-window} can be used to |
| 1149 | retrieve the least recently selected live window (@pxref{Cyclic Window |
| 1150 | Ordering}). |
| 1151 | |
| 1152 | @defmac save-selected-window forms@dots{} |
| 1153 | This macro records the selected frame, as well as the selected window |
| 1154 | of each frame, executes @var{forms} in sequence, then restores the |
| 1155 | earlier selected frame and windows. It also saves and restores the |
| 1156 | current buffer. It returns the value of the last form in @var{forms}. |
| 1157 | |
| 1158 | This macro does not save or restore anything about the sizes, |
| 1159 | arrangement or contents of windows; therefore, if @var{forms} change |
| 1160 | them, the change persists. If the previously selected window of some |
| 1161 | frame is no longer live at the time of exit from @var{forms}, that |
| 1162 | frame's selected window is left alone. If the previously selected |
| 1163 | window is no longer live, then whatever window is selected at the end of |
| 1164 | @var{forms} remains selected. The current buffer is restored if and |
| 1165 | only if it is still live when exiting @var{forms}. |
| 1166 | |
| 1167 | This macro changes neither the ordering of recently selected windows nor |
| 1168 | the buffer list. |
| 1169 | @end defmac |
| 1170 | |
| 1171 | @defmac with-selected-window window forms@dots{} |
| 1172 | This macro selects @var{window}, executes @var{forms} in sequence, then |
| 1173 | restores the previously selected window and current buffer. The ordering |
| 1174 | of recently selected windows and the buffer list remain unchanged unless |
| 1175 | you deliberately change them within @var{forms}, for example, by calling |
| 1176 | @code{select-window} with argument @var{norecord} @code{nil}. |
| 1177 | |
| 1178 | The order of recently selected windows and the buffer list are not |
| 1179 | changed by this macro. |
| 1180 | @end defmac |
| 1181 | |
| 1182 | @defun frame-selected-window &optional frame |
| 1183 | This function returns the window on @var{frame} that is selected |
| 1184 | within that frame. @var{frame} should be a live frame; if omitted or |
| 1185 | @code{nil}, it defaults to the selected frame. |
| 1186 | @end defun |
| 1187 | |
| 1188 | @defun set-frame-selected-window frame window &optional norecord |
| 1189 | This function makes @code{window} the window selected within the frame |
| 1190 | @var{frame}. @var{frame} should be a live frame; if omitted or |
| 1191 | @code{nil}, it defaults to the selected frame. @var{window} should be |
| 1192 | a live window; if omitted or @code{nil}, it defaults to the selected |
| 1193 | window. |
| 1194 | |
| 1195 | If @var{frame} is the selected frame, this makes @var{window} the |
| 1196 | selected window. |
| 1197 | |
| 1198 | If the optional argument @var{norecord} is non-@code{nil}, this |
| 1199 | function does not alter the list of most recently selected windows, |
| 1200 | nor the buffer list. |
| 1201 | @end defun |
| 1202 | |
| 1203 | @node Cyclic Window Ordering |
| 1204 | @section Cyclic Ordering of Windows |
| 1205 | @cindex cyclic ordering of windows |
| 1206 | @cindex ordering of windows, cyclic |
| 1207 | @cindex window ordering, cyclic |
| 1208 | |
| 1209 | When you use the command @kbd{C-x o} (@code{other-window}) to select |
| 1210 | some other window, it moves through live windows in a specific order. |
| 1211 | For any given configuration of windows, this order never varies. It |
| 1212 | is called the @dfn{cyclic ordering of windows}. |
| 1213 | |
| 1214 | The ordering is determined by a depth-first traversal of the frame's |
| 1215 | window tree, retrieving the live windows which are the leaf nodes of |
| 1216 | the tree (@pxref{Windows and Frames}). If the minibuffer is active, |
| 1217 | the minibuffer window is included too. The ordering is cyclic, so the |
| 1218 | last window in the sequence is followed by the first one. |
| 1219 | |
| 1220 | @defun next-window &optional window minibuf all-frames |
| 1221 | @cindex minibuffer window, and @code{next-window} |
| 1222 | This function returns a live window, the one following @var{window} in |
| 1223 | the cyclic ordering of windows. @var{window} should be a live window; |
| 1224 | if omitted or @code{nil}, it defaults to the selected window. |
| 1225 | |
| 1226 | The optional argument @var{minibuf} specifies whether minibuffer windows |
| 1227 | shall be included in the cyclic ordering. Normally, when @var{minibuf} |
| 1228 | is @code{nil}, a minibuffer window is included only if it is currently |
| 1229 | ``active''; this matches the behavior of @kbd{C-x o}. (Note that a |
| 1230 | minibuffer window is active as long as its minibuffer is in use; see |
| 1231 | @ref{Minibuffers}). |
| 1232 | |
| 1233 | If @var{minibuf} is @code{t}, the cyclic ordering includes all |
| 1234 | minibuffer windows. If @var{minibuf} is neither @code{t} nor |
| 1235 | @code{nil}, minibuffer windows are not included even if they are active. |
| 1236 | |
| 1237 | The optional argument @var{all-frames} specifies which frames to |
| 1238 | consider: |
| 1239 | |
| 1240 | @itemize @bullet |
| 1241 | @item @code{nil} |
| 1242 | means to consider windows on @var{window}'s frame. If the minibuffer |
| 1243 | window is considered (as specified by the @var{minibuf} argument), |
| 1244 | then frames that share the minibuffer window are considered too. |
| 1245 | |
| 1246 | @item @code{t} |
| 1247 | means to consider windows on all existing frames. |
| 1248 | |
| 1249 | @item @code{visible} |
| 1250 | means to consider windows on all visible frames. |
| 1251 | |
| 1252 | @item 0 |
| 1253 | means to consider windows on all visible or iconified frames. |
| 1254 | |
| 1255 | @item A frame |
| 1256 | means to consider windows on that specific frame. |
| 1257 | |
| 1258 | @item Anything else |
| 1259 | means to consider windows on @var{window}'s frame, and no others. |
| 1260 | @end itemize |
| 1261 | |
| 1262 | If more than one frame is considered, the cyclic ordering is obtained |
| 1263 | by appending the orderings for those frames, in the same order as the |
| 1264 | list of all live frames (@pxref{Finding All Frames}). |
| 1265 | @end defun |
| 1266 | |
| 1267 | @defun previous-window &optional window minibuf all-frames |
| 1268 | This function returns a live window, the one preceding @var{window} in |
| 1269 | the cyclic ordering of windows. The other arguments are handled like |
| 1270 | in @code{next-window}. |
| 1271 | @end defun |
| 1272 | |
| 1273 | @deffn Command other-window count &optional all-frames |
| 1274 | This function selects a live window, one @var{count} places from the |
| 1275 | selected window in the cyclic ordering of windows. If @var{count} is |
| 1276 | a positive number, it skips @var{count} windows forwards; if |
| 1277 | @var{count} is negative, it skips @minus{}@var{count} windows |
| 1278 | backwards; if @var{count} is zero, that simply re-selects the selected |
| 1279 | window. When called interactively, @var{count} is the numeric prefix |
| 1280 | argument. |
| 1281 | |
| 1282 | The optional argument @var{all-frames} has the same meaning as in |
| 1283 | @code{next-window}, like a @code{nil} @var{minibuf} argument to |
| 1284 | @code{next-window}. |
| 1285 | |
| 1286 | This function does not select a window that has a non-@code{nil} |
| 1287 | @code{no-other-window} window parameter (@pxref{Window Parameters}). |
| 1288 | @end deffn |
| 1289 | |
| 1290 | @defun walk-windows fun &optional minibuf all-frames |
| 1291 | This function calls the function @var{fun} once for each live window, |
| 1292 | with the window as the argument. |
| 1293 | |
| 1294 | It follows the cyclic ordering of windows. The optional arguments |
| 1295 | @var{minibuf} and @var{all-frames} specify the set of windows |
| 1296 | included; these have the same arguments as in @code{next-window}. If |
| 1297 | @var{all-frames} specifies a frame, the first window walked is the |
| 1298 | first window on that frame (the one returned by |
| 1299 | @code{frame-first-window}), not necessarily the selected window. |
| 1300 | |
| 1301 | If @var{fun} changes the window configuration by splitting or deleting |
| 1302 | windows, that does not alter the set of windows walked, which is |
| 1303 | determined prior to calling @var{fun} for the first time. |
| 1304 | @end defun |
| 1305 | |
| 1306 | @defun one-window-p &optional no-mini all-frames |
| 1307 | This function returns @code{t} if the selected window is the only live |
| 1308 | window, and @code{nil} otherwise. |
| 1309 | |
| 1310 | If the minibuffer window is active, it is normally considered (so that |
| 1311 | this function returns @code{nil}). However, if the optional argument |
| 1312 | @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even |
| 1313 | if active. The optional argument @var{all-frames} has the same |
| 1314 | meaning as for @code{next-window}. |
| 1315 | @end defun |
| 1316 | |
| 1317 | @cindex finding windows |
| 1318 | The following functions return a window which satisfies some |
| 1319 | criterion, without selecting it: |
| 1320 | |
| 1321 | @cindex least recently used window |
| 1322 | @defun get-lru-window &optional all-frames dedicated |
| 1323 | This function returns a live window which is heuristically the ``least |
| 1324 | recently used'' window. The optional argument @var{all-frames} has |
| 1325 | the same meaning as in @code{next-window}. |
| 1326 | |
| 1327 | If any full-width windows are present, only those windows are |
| 1328 | considered. The selected window is never returned, unless it is the |
| 1329 | only candidate. A minibuffer window is never a candidate. A |
| 1330 | dedicated window (@pxref{Dedicated Windows}) is never a candidate |
| 1331 | unless the optional argument @var{dedicated} is non-@code{nil}. |
| 1332 | @end defun |
| 1333 | |
| 1334 | @cindex largest window |
| 1335 | @defun get-largest-window &optional all-frames dedicated |
| 1336 | This function returns the window with the largest area (height times |
| 1337 | width). A minibuffer window is never a candidate. A dedicated window |
| 1338 | (@pxref{Dedicated Windows}) is never a candidate unless the optional |
| 1339 | argument @var{dedicated} is non-@code{nil}. |
| 1340 | |
| 1341 | If there are two candidate windows of the same size, this function |
| 1342 | prefers the one that comes first in the cyclic ordering of windows, |
| 1343 | starting from the selected window. |
| 1344 | |
| 1345 | The optional argument @var{all-frames} specifies the windows to |
| 1346 | search, and has the same meaning as in @code{next-window}. |
| 1347 | @end defun |
| 1348 | |
| 1349 | @cindex window that satisfies a predicate |
| 1350 | @cindex conditional selection of windows |
| 1351 | @defun get-window-with-predicate predicate &optional minibuf all-frames default |
| 1352 | This function calls the function @var{predicate} for each of the |
| 1353 | windows in the cyclic order of windows in turn, passing it the window |
| 1354 | as an argument. If the predicate returns non-@code{nil} for any |
| 1355 | window, this function stops and returns that window. If no such |
| 1356 | window is found, the return value is @var{default} (which defaults to |
| 1357 | @code{nil}). |
| 1358 | |
| 1359 | The optional arguments @var{minibuf} and @var{all-frames} specify the |
| 1360 | windows to search, and have the same meanings as in |
| 1361 | @code{next-window}. |
| 1362 | @end defun |
| 1363 | |
| 1364 | @node Buffers and Windows |
| 1365 | @section Buffers and Windows |
| 1366 | @cindex examining windows |
| 1367 | @cindex windows, controlling precisely |
| 1368 | @cindex buffers, controlled in windows |
| 1369 | |
| 1370 | This section describes low-level functions for examining and setting |
| 1371 | the contents of windows. @xref{Switching Buffers}, for higher-level |
| 1372 | functions for displaying a specific buffer in a window. |
| 1373 | |
| 1374 | @defun window-buffer &optional window |
| 1375 | This function returns the buffer that @var{window} is displaying. If |
| 1376 | @var{window} is omitted or @code{nil} it defaults to the selected |
| 1377 | window. If @var{window} is an internal window, this function returns |
| 1378 | @code{nil}. |
| 1379 | @end defun |
| 1380 | |
| 1381 | @defun set-window-buffer window buffer-or-name &optional keep-margins |
| 1382 | This function makes @var{window} display @var{buffer-or-name}. |
| 1383 | @var{window} should be a live window; if @code{nil}, it defaults to |
| 1384 | the selected window. @var{buffer-or-name} should be a buffer, or the |
| 1385 | name of an existing buffer. This function does not change which |
| 1386 | window is selected, nor does it directly change which buffer is |
| 1387 | current (@pxref{Current Buffer}). Its return value is @code{nil}. |
| 1388 | |
| 1389 | If @var{window} is @dfn{strongly dedicated} to a buffer and |
| 1390 | @var{buffer-or-name} does not specify that buffer, this function |
| 1391 | signals an error. @xref{Dedicated Windows}. |
| 1392 | |
| 1393 | By default, this function resets @var{window}'s position, display |
| 1394 | margins, fringe widths, and scroll bar settings, based on the local |
| 1395 | variables in the specified buffer. However, if the optional argument |
| 1396 | @var{keep-margins} is non-@code{nil}, it leaves the display margins |
| 1397 | and fringe widths unchanged. |
| 1398 | |
| 1399 | When writing an application, you should normally use the higher-level |
| 1400 | functions described in @ref{Switching Buffers}, instead of calling |
| 1401 | @code{set-window-buffer} directly. |
| 1402 | |
| 1403 | This function runs @code{window-scroll-functions}, followed by |
| 1404 | @code{window-configuration-change-hook}. @xref{Window Hooks}. |
| 1405 | @end defun |
| 1406 | |
| 1407 | @defvar buffer-display-count |
| 1408 | This buffer-local variable records the number of times a buffer has been |
| 1409 | displayed in a window. It is incremented each time |
| 1410 | @code{set-window-buffer} is called for the buffer. |
| 1411 | @end defvar |
| 1412 | |
| 1413 | @defvar buffer-display-time |
| 1414 | This buffer-local variable records the time at which a buffer was last |
| 1415 | displayed in a window. The value is @code{nil} if the buffer has |
| 1416 | never been displayed. It is updated each time |
| 1417 | @code{set-window-buffer} is called for the buffer, with the value |
| 1418 | returned by @code{current-time} (@pxref{Time of Day}). |
| 1419 | @end defvar |
| 1420 | |
| 1421 | @defun get-buffer-window &optional buffer-or-name all-frames |
| 1422 | This function returns the first window displaying @var{buffer-or-name} |
| 1423 | in the cyclic ordering of windows, starting from the selected window |
| 1424 | (@pxref{Cyclic Window Ordering}). If no such window exists, the |
| 1425 | return value is @code{nil}. |
| 1426 | |
| 1427 | @var{buffer-or-name} should be a buffer or the name of a buffer; if |
| 1428 | omitted or @code{nil}, it defaults to the current buffer. The |
| 1429 | optional argument @var{all-frames} specifies which windows to |
| 1430 | consider: |
| 1431 | |
| 1432 | @itemize @bullet |
| 1433 | @item |
| 1434 | @code{t} means consider windows on all existing frames. |
| 1435 | @item |
| 1436 | @code{visible} means consider windows on all visible frames. |
| 1437 | @item |
| 1438 | 0 means consider windows on all visible or iconified frames. |
| 1439 | @item |
| 1440 | A frame means consider windows on that frame only. |
| 1441 | @item |
| 1442 | Any other value means consider windows on the selected frame. |
| 1443 | @end itemize |
| 1444 | |
| 1445 | Note that these meanings differ slightly from those of the |
| 1446 | @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window |
| 1447 | Ordering}). This function may be changed in a future version of Emacs |
| 1448 | to eliminate this discrepancy. |
| 1449 | @end defun |
| 1450 | |
| 1451 | @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames |
| 1452 | This function returns a list of all windows currently displaying |
| 1453 | @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the |
| 1454 | name of an existing buffer. If omitted or @code{nil}, it defaults to |
| 1455 | the current buffer. |
| 1456 | |
| 1457 | The arguments @var{minibuf} and @var{all-frames} have the same |
| 1458 | meanings as in the function @code{next-window} (@pxref{Cyclic Window |
| 1459 | Ordering}). Note that the @var{all-frames} argument does @emph{not} |
| 1460 | behave exactly like in @code{get-buffer-window}. |
| 1461 | @end defun |
| 1462 | |
| 1463 | @deffn Command replace-buffer-in-windows &optional buffer-or-name |
| 1464 | This command replaces @var{buffer-or-name} with some other buffer, in |
| 1465 | all windows displaying it. @var{buffer-or-name} should be a buffer, |
| 1466 | or the name of an existing buffer; if omitted or @code{nil}, it |
| 1467 | defaults to the current buffer. |
| 1468 | |
| 1469 | The replacement buffer in each window is chosen via |
| 1470 | @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated |
| 1471 | window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated |
| 1472 | Windows}), unless it is the only window on its frame---if it is the |
| 1473 | only window, and that frame is not the only frame on its terminal, the |
| 1474 | frame is ``dismissed'' by calling the function specified by |
| 1475 | @code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the |
| 1476 | dedicated window is the only window on the only frame on its terminal, |
| 1477 | the buffer is replaced anyway. |
| 1478 | @end deffn |
| 1479 | |
| 1480 | @node Switching Buffers |
| 1481 | @section Switching to a Buffer in a Window |
| 1482 | @cindex switching to a buffer |
| 1483 | @cindex displaying a buffer |
| 1484 | |
| 1485 | This section describes high-level functions for switching to a |
| 1486 | specified buffer in some window. |
| 1487 | |
| 1488 | Do @emph{not} use these functions to make a buffer temporarily |
| 1489 | current just so a Lisp program can access or modify it. They have |
| 1490 | side-effects, such as changing window histories (@pxref{Window |
| 1491 | History}), which will surprise the user if used that way. If you want |
| 1492 | to make a buffer current to modify it in Lisp, use |
| 1493 | @code{with-current-buffer}, @code{save-current-buffer}, or |
| 1494 | @code{set-buffer}. @xref{Current Buffer}. |
| 1495 | |
| 1496 | @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window |
| 1497 | This function displays @var{buffer-or-name} in the selected window, |
| 1498 | and makes it the current buffer. (In contrast, @code{set-buffer} |
| 1499 | makes the buffer current but does not display it; @pxref{Current |
| 1500 | Buffer}). It is often used interactively (as the binding of @kbd{C-x |
| 1501 | b}), as well as in Lisp programs. The return value is the buffer |
| 1502 | switched to. |
| 1503 | |
| 1504 | If @var{buffer-or-name} is @code{nil}, it defaults to the buffer |
| 1505 | returned by @code{other-buffer} (@pxref{The Buffer List}). If |
| 1506 | @var{buffer-or-name} is a string that is not the name of any existing |
| 1507 | buffer, this function creates a new buffer with that name; the new |
| 1508 | buffer's major mode is determined by the variable @code{major-mode} |
| 1509 | (@pxref{Major Modes}). |
| 1510 | |
| 1511 | Normally the specified buffer is put at the front of the buffer |
| 1512 | list---both the global buffer list and the selected frame's buffer |
| 1513 | list (@pxref{The Buffer List}). However, this is not done if the |
| 1514 | optional argument @var{norecord} is non-@code{nil}. |
| 1515 | |
| 1516 | If this function is unable to display the buffer in the selected |
| 1517 | window---usually because the selected window is a minibuffer window or |
| 1518 | is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then |
| 1519 | it normally tries to display the buffer in some other window, in the |
| 1520 | manner of @code{pop-to-buffer} (see below). However, if the optional |
| 1521 | argument @var{force-same-window} is non-@code{nil}, it signals an error |
| 1522 | instead. |
| 1523 | @end deffn |
| 1524 | |
| 1525 | The next two functions are similar to @code{switch-to-buffer}, except |
| 1526 | for the described features. |
| 1527 | |
| 1528 | @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord |
| 1529 | This function makes the buffer specified by @var{buffer-or-name} |
| 1530 | current and displays it in some window other than the selected window. |
| 1531 | It uses the function @code{pop-to-buffer} internally (see below). |
| 1532 | |
| 1533 | If the selected window already displays the specified buffer, it |
| 1534 | continues to do so, but another window is nonetheless found to display |
| 1535 | it as well. |
| 1536 | |
| 1537 | The @var{buffer-or-name} and @var{norecord} arguments have the same |
| 1538 | meanings as in @code{switch-to-buffer}. |
| 1539 | @end deffn |
| 1540 | |
| 1541 | @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord |
| 1542 | This function makes the buffer specified by @var{buffer-or-name} |
| 1543 | current and displays it, usually in a new frame. It uses the function |
| 1544 | @code{pop-to-buffer} (see below). |
| 1545 | |
| 1546 | If the specified buffer is already displayed in another window, in any |
| 1547 | frame on the current terminal, this switches to that window instead of |
| 1548 | creating a new frame. However, the selected window is never used for |
| 1549 | this. |
| 1550 | |
| 1551 | The @var{buffer-or-name} and @var{norecord} arguments have the same |
| 1552 | meanings as in @code{switch-to-buffer}. |
| 1553 | @end deffn |
| 1554 | |
| 1555 | The above commands use the function @code{pop-to-buffer}, which |
| 1556 | flexibly displays a buffer in some window and selects that window for |
| 1557 | editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for |
| 1558 | displaying the buffer. Hence, all the variables affecting |
| 1559 | @code{display-buffer} will affect it as well. @xref{Choosing Window}, |
| 1560 | for the documentation of @code{display-buffer}. |
| 1561 | |
| 1562 | @defun pop-to-buffer buffer-or-name &optional action norecord |
| 1563 | This function makes @var{buffer-or-name} the current buffer and |
| 1564 | displays it in some window, preferably not the window previously |
| 1565 | selected. It then selects the displaying window. If that window is |
| 1566 | on a different graphical frame, that frame is given input focus if |
| 1567 | possible (@pxref{Input Focus}). The return value is the buffer that |
| 1568 | was switched to. |
| 1569 | |
| 1570 | If @var{buffer-or-name} is @code{nil}, it defaults to the buffer |
| 1571 | returned by @code{other-buffer} (@pxref{The Buffer List}). If |
| 1572 | @var{buffer-or-name} is a string that is not the name of any existing |
| 1573 | buffer, this function creates a new buffer with that name; the new |
| 1574 | buffer's major mode is determined by the variable @code{major-mode} |
| 1575 | (@pxref{Major Modes}). |
| 1576 | |
| 1577 | If @var{action} is non-@code{nil}, it should be a display action to |
| 1578 | pass to @code{display-buffer} (@pxref{Choosing Window}). |
| 1579 | Alternatively, a non-@code{nil}, non-list value means to pop to a |
| 1580 | window other than the selected one---even if the buffer is already |
| 1581 | displayed in the selected window. |
| 1582 | |
| 1583 | Like @code{switch-to-buffer}, this function updates the buffer list |
| 1584 | unless @var{norecord} is non-@code{nil}. |
| 1585 | @end defun |
| 1586 | |
| 1587 | @node Choosing Window |
| 1588 | @section Choosing a Window for Display |
| 1589 | |
| 1590 | The command @code{display-buffer} flexibly chooses a window for |
| 1591 | display, and displays a specified buffer in that window. It can be |
| 1592 | called interactively, via the key binding @kbd{C-x 4 C-o}. It is also |
| 1593 | used as a subroutine by many functions and commands, including |
| 1594 | @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching |
| 1595 | Buffers}). |
| 1596 | |
| 1597 | @cindex display action |
| 1598 | @cindex action function, for @code{display-buffer} |
| 1599 | @cindex action alist, for @code{display-buffer} |
| 1600 | This command performs several complex steps to find a window to |
| 1601 | display in. These steps are described by means of @dfn{display |
| 1602 | actions}, which have the form @code{(@var{function} . @var{alist})}. |
| 1603 | Here, @var{function} is either a function or a list of functions, |
| 1604 | which we refer to as @dfn{action functions}; @var{alist} is an |
| 1605 | association list, which we refer to as @dfn{action alists}. |
| 1606 | |
| 1607 | An action function accepts two arguments: the buffer to display and |
| 1608 | an action alist. It attempts to display the buffer in some window, |
| 1609 | picking or creating a window according to its own criteria. If |
| 1610 | successful, it returns the window; otherwise, it returns @code{nil}. |
| 1611 | @xref{Display Action Functions}, for a list of predefined action |
| 1612 | functions. |
| 1613 | |
| 1614 | @code{display-buffer} works by combining display actions from |
| 1615 | several sources, and calling the action functions in turn, until one |
| 1616 | of them manages to display the buffer and returns a non-@code{nil} |
| 1617 | value. |
| 1618 | |
| 1619 | @deffn Command display-buffer buffer-or-name &optional action frame |
| 1620 | This command makes @var{buffer-or-name} appear in some window, without |
| 1621 | selecting the window or making the buffer current. The argument |
| 1622 | @var{buffer-or-name} must be a buffer or the name of an existing |
| 1623 | buffer. The return value is the window chosen to display the buffer. |
| 1624 | |
| 1625 | The optional argument @var{action}, if non-@code{nil}, should normally |
| 1626 | be a display action (described above). @code{display-buffer} builds a |
| 1627 | list of action functions and an action alist, by consolidating display |
| 1628 | actions from the following sources (in order): |
| 1629 | |
| 1630 | @itemize |
| 1631 | @item |
| 1632 | The variable @code{display-buffer-overriding-action}. |
| 1633 | |
| 1634 | @item |
| 1635 | The user option @code{display-buffer-alist}. |
| 1636 | |
| 1637 | @item |
| 1638 | A special action for handling @code{special-display-buffer-names} and |
| 1639 | @code{special-display-regexps}, if either of those variables is |
| 1640 | non-@code{nil}. @xref{Choosing Window Options}. |
| 1641 | |
| 1642 | @item |
| 1643 | The @var{action} argument. |
| 1644 | |
| 1645 | @item |
| 1646 | The user option @code{display-buffer-base-action}. |
| 1647 | |
| 1648 | @item |
| 1649 | The constant @code{display-buffer-fallback-action}. |
| 1650 | @end itemize |
| 1651 | |
| 1652 | @noindent |
| 1653 | Each action function is called in turn, passing the buffer as the |
| 1654 | first argument and the combined action alist as the second argument, |
| 1655 | until one of the functions returns non-@code{nil}. |
| 1656 | |
| 1657 | The argument @var{action} can also have a non-@code{nil}, non-list |
| 1658 | value. This has the special meaning that the buffer should be |
| 1659 | displayed in a window other than the selected one, even if the |
| 1660 | selected window is already displaying it. If called interactively |
| 1661 | with a prefix argument, @var{action} is @code{t}. |
| 1662 | |
| 1663 | The optional argument @var{frame}, if non-@code{nil}, specifies which |
| 1664 | frames to check when deciding whether the buffer is already displayed. |
| 1665 | It is equivalent to adding an element @code{(reusable-frames |
| 1666 | . @var{frame})} to the action alist of @var{action}. @xref{Display |
| 1667 | Action Functions}. |
| 1668 | @end deffn |
| 1669 | |
| 1670 | @defvar display-buffer-overriding-action |
| 1671 | The value of this variable should be a display action, which is |
| 1672 | treated with the highest priority by @code{display-buffer}. The |
| 1673 | default value is empty, i.e. @code{(nil . nil)}. |
| 1674 | @end defvar |
| 1675 | |
| 1676 | @defopt display-buffer-alist |
| 1677 | The value of this option is an alist mapping regular expressions to |
| 1678 | display actions. If the name of the buffer passed to |
| 1679 | @code{display-buffer} matches a regular expression in this alist, then |
| 1680 | @code{display-buffer} uses the corresponding display action. |
| 1681 | @end defopt |
| 1682 | |
| 1683 | @defopt display-buffer-base-action |
| 1684 | The value of this option should be a display action. This option can |
| 1685 | be used to define a ``standard'' display action for calls to |
| 1686 | @code{display-buffer}. |
| 1687 | @end defopt |
| 1688 | |
| 1689 | @defvr Constant display-buffer-fallback-action |
| 1690 | This display action specifies the fallback behavior for |
| 1691 | @code{display-buffer} if no other display actions are given. |
| 1692 | @end defvr |
| 1693 | |
| 1694 | @node Display Action Functions |
| 1695 | @section Action Functions for @code{display-buffer} |
| 1696 | |
| 1697 | The following basic action functions are defined in Emacs. Each of |
| 1698 | these functions takes two arguments: @var{buffer}, the buffer to |
| 1699 | display, and @var{alist}, an action alist. Each action function |
| 1700 | returns the window if it succeeds, and @code{nil} if it fails. |
| 1701 | |
| 1702 | @defun display-buffer-same-window buffer alist |
| 1703 | This function tries to display @var{buffer} in the selected window. |
| 1704 | It fails if the selected window is a minibuffer window or is dedicated |
| 1705 | to another buffer (@pxref{Dedicated Windows}). It also fails if |
| 1706 | @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry. |
| 1707 | @end defun |
| 1708 | |
| 1709 | @defun display-buffer-reuse-window buffer alist |
| 1710 | This function tries to ``display'' @var{buffer} by finding a window |
| 1711 | that is already displaying it. |
| 1712 | |
| 1713 | If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, |
| 1714 | the selected window is not eligible for reuse. If @var{alist} |
| 1715 | contains a @code{reusable-frames} entry, its value determines which |
| 1716 | frames to search for a reusable window: |
| 1717 | |
| 1718 | @itemize @bullet |
| 1719 | @item |
| 1720 | @code{nil} means consider windows on the selected frame. |
| 1721 | (Actually, the last non-minibuffer frame.) |
| 1722 | @item |
| 1723 | @code{t} means consider windows on all frames. |
| 1724 | @item |
| 1725 | @code{visible} means consider windows on all visible frames. |
| 1726 | @item |
| 1727 | 0 means consider windows on all visible or iconified frames. |
| 1728 | @item |
| 1729 | A frame means consider windows on that frame only. |
| 1730 | @end itemize |
| 1731 | |
| 1732 | If @var{alist} contains no @code{reusable-frames} entry, this function |
| 1733 | normally searches just the selected frame; however, if either the |
| 1734 | variable @code{display-buffer-reuse-frames} or the variable |
| 1735 | @code{pop-up-frames} is non-@code{nil}, it searches all frames on the |
| 1736 | current terminal. @xref{Choosing Window Options}. |
| 1737 | |
| 1738 | If this function chooses a window on another frame, it makes that |
| 1739 | frame visible and raises it if necessary. |
| 1740 | @end defun |
| 1741 | |
| 1742 | @defun display-buffer-pop-up-frame buffer alist |
| 1743 | This function creates a new frame, and displays the buffer in that |
| 1744 | frame's window. It actually performs the frame creation by calling |
| 1745 | the function specified in @code{pop-up-frame-function} |
| 1746 | (@pxref{Choosing Window Options}). |
| 1747 | @end defun |
| 1748 | |
| 1749 | @defun display-buffer-pop-up-window buffer alist |
| 1750 | This function tries to display @var{buffer} by splitting the largest |
| 1751 | or least recently-used window (typically one on the selected frame). |
| 1752 | It actually performs the split by calling the function specified in |
| 1753 | @code{split-window-preferred-function} (@pxref{Choosing Window |
| 1754 | Options}). |
| 1755 | |
| 1756 | It can fail if no window splitting can be performed for some reason |
| 1757 | (e.g. if there is just one frame and it has an @code{unsplittable} |
| 1758 | frame parameter; @pxref{Buffer Parameters}). |
| 1759 | @end defun |
| 1760 | |
| 1761 | @defun display-buffer-use-some-window buffer alist |
| 1762 | This function tries to display @var{buffer} by choosing an existing |
| 1763 | window and displaying the buffer in that window. It can fail if all |
| 1764 | windows are dedicated to another buffer (@pxref{Dedicated Windows}). |
| 1765 | @end defun |
| 1766 | |
| 1767 | @node Choosing Window Options |
| 1768 | @section Additional Options for Displaying Buffers |
| 1769 | |
| 1770 | The behavior of the standard display actions of @code{display-buffer} |
| 1771 | (@pxref{Choosing Window}) can be modified by a variety of user |
| 1772 | options. |
| 1773 | |
| 1774 | @defopt display-buffer-reuse-frames |
| 1775 | If the value of this variable is non-@code{nil}, @code{display-buffer} |
| 1776 | may search all frames on the current terminal when looking for a |
| 1777 | window already displaying the specified buffer. The default is |
| 1778 | @code{nil}. This variable is consulted by the action function |
| 1779 | @code{display-buffer-reuse-window} (@pxref{Display Action Functions}). |
| 1780 | @end defopt |
| 1781 | |
| 1782 | @defopt pop-up-windows |
| 1783 | If the value of this variable is non-@code{nil}, @code{display-buffer} |
| 1784 | is allowed to split an existing window to make a new window for |
| 1785 | displaying in. This is the default. |
| 1786 | |
| 1787 | This variable is provided mainly for backward compatibility. It is |
| 1788 | obeyed by @code{display-buffer} via a special mechanism in |
| 1789 | @code{display-buffer-fallback-action}, which only calls the action |
| 1790 | function @code{display-buffer-pop-up-window} (@pxref{Display Action |
| 1791 | Functions}) when the value is @code{nil}. It is not consulted by |
| 1792 | @code{display-buffer-pop-up-window} itself, which the user may specify |
| 1793 | directly in @code{display-buffer-alist} etc. |
| 1794 | @end defopt |
| 1795 | |
| 1796 | @defopt split-window-preferred-function |
| 1797 | This variable specifies a function for splitting a window, in order to |
| 1798 | make a new window for displaying a buffer. It is used by the |
| 1799 | @code{display-buffer-pop-up-window} action function to actually split |
| 1800 | the window (@pxref{Display Action Functions}). |
| 1801 | |
| 1802 | The default value is @code{split-window-sensibly}, which is documented |
| 1803 | below. The value must be a function that takes one argument, a |
| 1804 | window, and return either a new window (which is used to display the |
| 1805 | desired buffer) or @code{nil} (which means the splitting failed). |
| 1806 | @end defopt |
| 1807 | |
| 1808 | @defun split-window-sensibly window |
| 1809 | This function tries to split @code{window}, and return the newly |
| 1810 | created window. If @code{window} cannot be split, it returns |
| 1811 | @code{nil}. |
| 1812 | |
| 1813 | This function obeys the usual rules that determine when a window may |
| 1814 | be split (@pxref{Splitting Windows}). It first tries to split by |
| 1815 | placing the new window below, subject to the restriction imposed by |
| 1816 | @code{split-height-threshold} (see below) in addition to any other |
| 1817 | restrictions. If that fails, it tries to split by placing the new |
| 1818 | window to the right, subject to @code{split-width-threshold} (see |
| 1819 | below). If that fails, and the window is the only window on its |
| 1820 | frame, this function again tries to split and place the new window |
| 1821 | below, disregarding @code{split-height-threshold}. If this fails as |
| 1822 | well, this function gives up and returns @code{nil}. |
| 1823 | @end defun |
| 1824 | |
| 1825 | @defopt split-height-threshold |
| 1826 | This variable, used by @code{split-window-sensibly}, specifies whether |
| 1827 | to split the window placing the new window below. If it is an |
| 1828 | integer, that means to split only if the original window has at least |
| 1829 | that many lines. If it is @code{nil}, that means not to split this |
| 1830 | way. |
| 1831 | @end defopt |
| 1832 | |
| 1833 | @defopt split-width-threshold |
| 1834 | This variable, used by @code{split-window-sensibly}, specifies whether |
| 1835 | to split the window placing the new window to the right. If the value |
| 1836 | is an integer, that means to split only if the original window has at |
| 1837 | least that many columns. If the value is @code{nil}, that means not |
| 1838 | to split this way. |
| 1839 | @end defopt |
| 1840 | |
| 1841 | @defopt pop-up-frames |
| 1842 | If the value of this variable is non-@code{nil}, that means |
| 1843 | @code{display-buffer} may display buffers by making new frames. The |
| 1844 | default is @code{nil}. |
| 1845 | |
| 1846 | A non-@code{nil} value also means that when @code{display-buffer} is |
| 1847 | looking for a window already displaying @var{buffer-or-name}, it can |
| 1848 | search any visible or iconified frame, not just the selected frame. |
| 1849 | |
| 1850 | This variable is provided mainly for backward compatibility. It is |
| 1851 | obeyed by @code{display-buffer} via a special mechanism in |
| 1852 | @code{display-buffer-fallback-action}, which calls the action function |
| 1853 | @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions}) |
| 1854 | if the value is non-@code{nil}. (This is done before attempting to |
| 1855 | split a window.) This variable is not consulted by |
| 1856 | @code{display-buffer-pop-up-frame} itself, which the user may specify |
| 1857 | directly in @code{display-buffer-alist} etc. |
| 1858 | @end defopt |
| 1859 | |
| 1860 | @defopt pop-up-frame-function |
| 1861 | This variable specifies a function for creating a new frame, in order |
| 1862 | to make a new window for displaying a buffer. It is used by the |
| 1863 | @code{display-buffer-pop-up-frame} action function (@pxref{Display |
| 1864 | Action Functions}). |
| 1865 | |
| 1866 | The value should be a function that takes no arguments and returns a |
| 1867 | frame, or @code{nil} if no frame could be created. The default value |
| 1868 | is a function that creates a frame using the parameters specified by |
| 1869 | @code{pop-up-frame-alist} (see below). |
| 1870 | @end defopt |
| 1871 | |
| 1872 | @defopt pop-up-frame-alist |
| 1873 | This variable holds an alist of frame parameters (@pxref{Frame |
| 1874 | Parameters}), which is used by the default function in |
| 1875 | @code{pop-up-frame-function} to make a new frame. The default is |
| 1876 | @code{nil}. |
| 1877 | @end defopt |
| 1878 | |
| 1879 | @defopt special-display-buffer-names |
| 1880 | A list of buffer names identifying buffers that should be displayed |
| 1881 | specially. If the name of @var{buffer-or-name} is in this list, |
| 1882 | @code{display-buffer} handles the buffer specially. By default, special |
| 1883 | display means to give the buffer a dedicated frame. |
| 1884 | |
| 1885 | If an element is a list, instead of a string, then the @sc{car} of that |
| 1886 | list is the buffer name, and the rest of that list says how to create |
| 1887 | the frame. There are two possibilities for the rest of that list (its |
| 1888 | @sc{cdr}): It can be an alist, specifying frame parameters, or it can |
| 1889 | contain a function and arguments to give to it. (The function's first |
| 1890 | argument is always the buffer to be displayed; the arguments from the |
| 1891 | list come after that.) |
| 1892 | |
| 1893 | For example: |
| 1894 | |
| 1895 | @example |
| 1896 | (("myfile" (minibuffer) (menu-bar-lines . 0))) |
| 1897 | @end example |
| 1898 | |
| 1899 | @noindent |
| 1900 | specifies to display a buffer named @samp{myfile} in a dedicated frame |
| 1901 | with specified @code{minibuffer} and @code{menu-bar-lines} parameters. |
| 1902 | |
| 1903 | The list of frame parameters can also use the phony frame parameters |
| 1904 | @code{same-frame} and @code{same-window}. If the specified frame |
| 1905 | parameters include @code{(same-window . @var{value})} and @var{value} |
| 1906 | is non-@code{nil}, that means to display the buffer in the current |
| 1907 | selected window. Otherwise, if they include @code{(same-frame . |
| 1908 | @var{value})} and @var{value} is non-@code{nil}, that means to display |
| 1909 | the buffer in a new window in the currently selected frame. |
| 1910 | @end defopt |
| 1911 | |
| 1912 | @defopt special-display-regexps |
| 1913 | A list of regular expressions specifying buffers that should be |
| 1914 | displayed specially. If the buffer's name matches any of the regular |
| 1915 | expressions in this list, @code{display-buffer} handles the buffer |
| 1916 | specially. By default, special display means to give the buffer a |
| 1917 | dedicated frame. |
| 1918 | |
| 1919 | If an element is a list, instead of a string, then the @sc{car} of the |
| 1920 | list is the regular expression, and the rest of the list says how to |
| 1921 | create the frame. See @code{special-display-buffer-names} above. |
| 1922 | @end defopt |
| 1923 | |
| 1924 | @defun special-display-p buffer-name |
| 1925 | This function returns non-@code{nil} if displaying a buffer |
| 1926 | named @var{buffer-name} with @code{display-buffer} would |
| 1927 | create a special frame. The value is @code{t} if it would |
| 1928 | use the default frame parameters, or else the specified list |
| 1929 | of frame parameters. |
| 1930 | @end defun |
| 1931 | |
| 1932 | @defopt special-display-function |
| 1933 | This variable holds the function to call to display a buffer specially. |
| 1934 | It receives the buffer as an argument, and should return the window in |
| 1935 | which it is displayed. The default value of this variable is |
| 1936 | @code{special-display-popup-frame}, see below. |
| 1937 | @end defopt |
| 1938 | |
| 1939 | @defun special-display-popup-frame buffer &optional args |
| 1940 | This function tries to make @var{buffer} visible in a frame of its own. |
| 1941 | If @var{buffer} is already displayed in some window, it makes that |
| 1942 | window's frame visible and raises it. Otherwise, it creates a frame |
| 1943 | that is dedicated to @var{buffer}. The return value is the window used |
| 1944 | to display @var{buffer}. |
| 1945 | |
| 1946 | If @var{args} is an alist, it specifies frame parameters for the new |
| 1947 | frame. If @var{args} is a list whose @sc{car} is a symbol, then |
| 1948 | @code{(car @var{args})} is called as a function to actually create and |
| 1949 | set up the frame; it is called with @var{buffer} as first argument, and |
| 1950 | @code{(cdr @var{args})} as additional arguments. |
| 1951 | |
| 1952 | This function always uses an existing window displaying @var{buffer}, |
| 1953 | whether or not it is in a frame of its own; but if you set up the above |
| 1954 | variables in your init file, before @var{buffer} was created, then |
| 1955 | presumably the window was previously made by this function. |
| 1956 | @end defun |
| 1957 | |
| 1958 | @defopt special-display-frame-alist |
| 1959 | @anchor{Definition of special-display-frame-alist} |
| 1960 | This variable holds frame parameters for |
| 1961 | @code{special-display-popup-frame} to use when it creates a frame. |
| 1962 | @end defopt |
| 1963 | |
| 1964 | @defopt same-window-buffer-names |
| 1965 | A list of buffer names for buffers that should be displayed in the |
| 1966 | selected window. If the buffer's name is in this list, |
| 1967 | @code{display-buffer} handles the buffer by switching to it in the |
| 1968 | selected window. |
| 1969 | @end defopt |
| 1970 | |
| 1971 | @defopt same-window-regexps |
| 1972 | A list of regular expressions that specify buffers that should be |
| 1973 | displayed in the selected window. If the buffer's name matches any of |
| 1974 | the regular expressions in this list, @code{display-buffer} handles the |
| 1975 | buffer by switching to it in the selected window. |
| 1976 | @end defopt |
| 1977 | |
| 1978 | @defun same-window-p buffer-name |
| 1979 | This function returns @code{t} if displaying a buffer |
| 1980 | named @var{buffer-name} with @code{display-buffer} would |
| 1981 | put it in the selected window. |
| 1982 | @end defun |
| 1983 | |
| 1984 | @c Emacs 19 feature |
| 1985 | @defopt display-buffer-function |
| 1986 | This variable is the most flexible way to customize the behavior of |
| 1987 | @code{display-buffer}. If it is non-@code{nil}, it should be a function |
| 1988 | that @code{display-buffer} calls to do the work. The function should |
| 1989 | accept two arguments, the first two arguments that @code{display-buffer} |
| 1990 | received. It should choose or create a window, display the specified |
| 1991 | buffer in it, and then return the window. |
| 1992 | |
| 1993 | This variable takes precedence over all the other options described |
| 1994 | above. |
| 1995 | @end defopt |
| 1996 | |
| 1997 | @node Window History |
| 1998 | @section Window History |
| 1999 | @cindex window history |
| 2000 | |
| 2001 | Each window remembers the buffers it has displayed earlier and the order |
| 2002 | in which these buffers have been removed from it. This history is used, |
| 2003 | for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and |
| 2004 | Windows}). This list is automatically maintained by Emacs, but you can |
| 2005 | use the following functions to explicitly inspect or alter it: |
| 2006 | |
| 2007 | @defun window-prev-buffers &optional window |
| 2008 | This function returns a list specifying the previous contents of |
| 2009 | @var{window}, which should be a live window and defaults to the |
| 2010 | selected window. |
| 2011 | |
| 2012 | Each list element has the form @code{(@var{buffer} @var{window-start} |
| 2013 | @var{window-pos})}, where @var{buffer} is a buffer previously shown in |
| 2014 | the window, @var{window-start} is the window start position when that |
| 2015 | buffer was last shown, and @var{window-pos} is the point position when |
| 2016 | that buffer was last shown. |
| 2017 | |
| 2018 | The list is ordered so that earlier elements correspond to more |
| 2019 | recently-shown buffers, and the first element usually corresponds to the |
| 2020 | buffer most recently removed from the window. |
| 2021 | @end defun |
| 2022 | |
| 2023 | @defun set-window-prev-buffers window prev-buffers |
| 2024 | This function sets @var{window}'s previous buffers to the value of |
| 2025 | @var{prev-buffers}. The argument @var{window} must be a live window |
| 2026 | and defaults to the selected one. The argument @var{prev-buffers} |
| 2027 | should be a list of the same form as that returned by |
| 2028 | @code{window-prev-buffers}. |
| 2029 | @end defun |
| 2030 | |
| 2031 | In addition, each buffer maintains a list of @dfn{next buffers}, which |
| 2032 | is a list of buffers re-shown by @code{switch-to-prev-buffer} (see |
| 2033 | below). This list is mainly used by @code{switch-to-prev-buffer} and |
| 2034 | @code{switch-to-next-buffer} for choosing buffers to switch to. |
| 2035 | |
| 2036 | @defun window-next-buffers &optional window |
| 2037 | This function returns the list of buffers recently re-shown in |
| 2038 | @var{window} via @code{switch-to-prev-buffer}. The @var{window} |
| 2039 | argument must denote a live window or @code{nil} (meaning the selected |
| 2040 | window). |
| 2041 | @end defun |
| 2042 | |
| 2043 | @defun set-window-next-buffers window next-buffers |
| 2044 | This function sets the next buffer list of @var{window} to |
| 2045 | @var{next-buffers}. The @var{window} argument should be a live window |
| 2046 | or @code{nil} (meaning the selected window). The argument |
| 2047 | @var{next-buffers} should be a list of buffers. |
| 2048 | @end defun |
| 2049 | |
| 2050 | The following commands can be used to cycle through the global buffer |
| 2051 | list, much like @code{bury-buffer} and @code{unbury-buffer}. However, |
| 2052 | they cycle according to the specified window's history list, rather |
| 2053 | than the global buffer list. In addition, they restore |
| 2054 | window-specific window start and point positions, and may show a |
| 2055 | buffer even if it is already shown in another window. The |
| 2056 | @code{switch-to-prev-buffer} command, in particular, is used by |
| 2057 | @code{replace-buffer-in-windows}, @code{bury-buffer} and |
| 2058 | @code{quit-window} to find a replacement buffer for a window. |
| 2059 | |
| 2060 | @deffn Command switch-to-prev-buffer &optional window bury-or-kill |
| 2061 | This command displays the previous buffer in @var{window}. The |
| 2062 | argument @var{window} should be a live window or @code{nil} (meaning |
| 2063 | the selected window). If the optional argument @var{bury-or-kill} is |
| 2064 | non-@code{nil}, this means that the buffer currently shown in |
| 2065 | @var{window} is about to be buried or killed and consequently shall |
| 2066 | not be switched to in future invocations of this command. |
| 2067 | |
| 2068 | The previous buffer is usually the buffer shown before the buffer |
| 2069 | currently shown in @var{window}. However, a buffer that has been buried |
| 2070 | or killed or has been already shown by a recent invocation of |
| 2071 | @code{switch-to-prev-buffer} does not qualify as previous buffer. |
| 2072 | |
| 2073 | If repeated invocations of this command have already shown all buffers |
| 2074 | previously shown in @var{window}, further invocations will show buffers |
| 2075 | from the buffer list of the frame @var{window} appears on (@pxref{The |
| 2076 | Buffer List}). |
| 2077 | @end deffn |
| 2078 | |
| 2079 | @deffn Command switch-to-next-buffer &optional window |
| 2080 | This command switches to the next buffer in @var{window} thus undoing |
| 2081 | the effect of the last @code{switch-to-prev-buffer} command in |
| 2082 | @var{window}. The argument @var{window} must be a live window and |
| 2083 | defaults to the selected one. |
| 2084 | |
| 2085 | If there is no recent invocation of a @code{switch-to-prev-buffer} that |
| 2086 | can be undone, this function tries to show a buffer from the buffer list |
| 2087 | of the frame @var{window} appears on (@pxref{The Buffer List}). |
| 2088 | @end deffn |
| 2089 | |
| 2090 | |
| 2091 | @node Dedicated Windows |
| 2092 | @section Dedicated Windows |
| 2093 | @cindex dedicated window |
| 2094 | |
| 2095 | Functions for displaying a buffer can be told to not use specific |
| 2096 | windows by marking these windows as @dfn{dedicated} to their buffers. |
| 2097 | @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated |
| 2098 | window for displaying another buffer in it. @code{get-lru-window} and |
| 2099 | @code{get-largest-window} (@pxref{Selecting Windows}) do not consider |
| 2100 | dedicated windows as candidates when their @var{dedicated} argument is |
| 2101 | non-@code{nil}. The behavior of @code{set-window-buffer} |
| 2102 | (@pxref{Buffers and Windows}) with respect to dedicated windows is |
| 2103 | slightly different, see below. |
| 2104 | |
| 2105 | When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to |
| 2106 | delete a dedicated window and that window is the only window on its |
| 2107 | frame, it deletes the window's frame too, provided there are other |
| 2108 | frames left. @code{replace-buffer-in-windows} (@pxref{Switching |
| 2109 | Buffers}) tries to delete all dedicated windows showing its buffer |
| 2110 | argument. When such a window is the only window on its frame, that |
| 2111 | frame is deleted, provided there are other frames left. If there are |
| 2112 | no more frames left, some other buffer is displayed in the window, and |
| 2113 | the window is marked as non-dedicated. |
| 2114 | |
| 2115 | When you kill a buffer (@pxref{Killing Buffers}) displayed in a |
| 2116 | dedicated window, any such window usually gets deleted too, since |
| 2117 | @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning |
| 2118 | up windows. Burying a buffer (@pxref{The Buffer List}) deletes the |
| 2119 | selected window if it is dedicated to that buffer. If, however, that |
| 2120 | window is the only window on its frame, @code{bury-buffer} displays |
| 2121 | another buffer in it and iconifies the frame. |
| 2122 | |
| 2123 | @defun window-dedicated-p &optional window |
| 2124 | This function returns non-@code{nil} if @var{window} is dedicated to its |
| 2125 | buffer and @code{nil} otherwise. More precisely, the return value is |
| 2126 | the value assigned by the last call of @code{set-window-dedicated-p} for |
| 2127 | @var{window} or @code{nil} if that function was never called with |
| 2128 | @var{window} as its argument. The default for @var{window} is the |
| 2129 | selected window. |
| 2130 | @end defun |
| 2131 | |
| 2132 | @defun set-window-dedicated-p window flag |
| 2133 | This function marks @var{window} as dedicated to its buffer if |
| 2134 | @var{flag} is non-@code{nil}, and non-dedicated otherwise. |
| 2135 | |
| 2136 | As a special case, if @var{flag} is @code{t}, @var{window} becomes |
| 2137 | @dfn{strongly} dedicated to its buffer. @code{set-window-buffer} |
| 2138 | signals an error when the window it acts upon is strongly dedicated to |
| 2139 | its buffer and does not already display the buffer it is asked to |
| 2140 | display. Other functions do not treat @code{t} differently from any |
| 2141 | non-@code{nil} value. |
| 2142 | @end defun |
| 2143 | |
| 2144 | |
| 2145 | @node Quitting Windows |
| 2146 | @section Quitting Windows |
| 2147 | |
| 2148 | When you want to get rid of a window used for displaying a buffer you |
| 2149 | can call @code{delete-window} or @code{delete-windows-on} |
| 2150 | (@pxref{Deleting Windows}) to remove that window from its frame. If the |
| 2151 | buffer is shown on a separate frame, you might want to call |
| 2152 | @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other |
| 2153 | hand, a window has been reused for displaying the buffer, you might |
| 2154 | prefer showing the buffer previously shown in that window by calling the |
| 2155 | function @code{switch-to-prev-buffer} (@pxref{Window History}). |
| 2156 | Finally, you might want to either bury (@pxref{The Buffer List}) or kill |
| 2157 | (@pxref{Killing Buffers}) the window's buffer. |
| 2158 | |
| 2159 | The following function uses information on how the window for |
| 2160 | displaying the buffer was obtained in the first place thus attempting to |
| 2161 | automatize the above decisions for you. |
| 2162 | |
| 2163 | @deffn Command quit-window &optional kill window |
| 2164 | This command quits @var{window} and buries its buffer. The argument |
| 2165 | @var{window} must be a live window and defaults to the selected one. |
| 2166 | With prefix argument @var{kill} non-@code{nil}, it kills the buffer |
| 2167 | instead of burying it. |
| 2168 | |
| 2169 | Quitting @var{window} means to proceed as follows: If @var{window} was |
| 2170 | created specially for displaying its current buffer, delete @var{window} |
| 2171 | provided its frame contains at least one other live window. If |
| 2172 | @var{window} is the only window on its frame and there are other frames |
| 2173 | on the frame's terminal, the value of @var{kill} determines how to |
| 2174 | proceed with the window. If @var{kill} is @code{nil}, the fate of the |
| 2175 | frame is determined by calling @code{frame-auto-hide-function} (see |
| 2176 | below) with that frame as sole argument. If @var{kill} is |
| 2177 | non-@code{nil}, the frame is deleted unconditionally. |
| 2178 | |
| 2179 | If @var{window} was reused for displaying its buffer, this command tries |
| 2180 | to display the buffer previously shown in it. It also tries to restore |
| 2181 | the window start (@pxref{Window Start and End}) and point (@pxref{Window |
| 2182 | Point}) positions of the previously shown buffer. If, in addition, the |
| 2183 | current buffer was temporarily resized, this command will also try to |
| 2184 | restore the original height of @var{window}. |
| 2185 | |
| 2186 | The three cases described so far require that the buffer shown in |
| 2187 | @var{window} is still the buffer displayed by the last buffer display |
| 2188 | function for this window. If another buffer has been shown in the |
| 2189 | meantime or the buffer previously shown no longer exists, this command |
| 2190 | calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some |
| 2191 | other buffer instead. |
| 2192 | @end deffn |
| 2193 | |
| 2194 | The function @code{quit-window} bases its decisions on information |
| 2195 | stored in @var{window}'s @code{quit-restore} window parameter |
| 2196 | (@pxref{Window Parameters}) and resets that parameter to @code{nil} |
| 2197 | after it's done. |
| 2198 | |
| 2199 | The following option specifies how to deal with a frame containing just |
| 2200 | one window that shall be either quit or whose buffer shall be buried. |
| 2201 | |
| 2202 | @defopt frame-auto-hide-function |
| 2203 | The function specified by this option is called to automatically hide |
| 2204 | frames. This function is called with one argument - a frame. |
| 2205 | |
| 2206 | The function specified here is called by @code{bury-buffer} (@pxref{The |
| 2207 | Buffer List}) when the selected window is dedicated and shows the buffer |
| 2208 | that shall be buried. It is also called by @code{quit-window} (see |
| 2209 | above) when the frame of the window that shall be quit has been |
| 2210 | specially created for displaying that window's buffer and the buffer |
| 2211 | shall be buried. |
| 2212 | |
| 2213 | The default is to call @code{iconify-frame} (@pxref{Visibility of |
| 2214 | Frames}). Alternatively, you may either specify @code{delete-frame} |
| 2215 | (@pxref{Deleting Frames}) to remove the frame from its display, |
| 2216 | @code{ignore} to leave the frame unchanged, or any other function that |
| 2217 | can take a frame as its sole argument. |
| 2218 | |
| 2219 | Note that the function specified by this option is called if and only if |
| 2220 | there's at least one other frame on the terminal of the frame it's |
| 2221 | supposed to handle and that frame contains only one live window. |
| 2222 | @end defopt |
| 2223 | |
| 2224 | |
| 2225 | @node Window Point |
| 2226 | @section Windows and Point |
| 2227 | @cindex window position |
| 2228 | @cindex window point |
| 2229 | @cindex position in window |
| 2230 | @cindex point in window |
| 2231 | |
| 2232 | Each window has its own value of point (@pxref{Point}), independent of |
| 2233 | the value of point in other windows displaying the same buffer. This |
| 2234 | makes it useful to have multiple windows showing one buffer. |
| 2235 | |
| 2236 | @itemize @bullet |
| 2237 | @item |
| 2238 | The window point is established when a window is first created; it is |
| 2239 | initialized from the buffer's point, or from the window point of another |
| 2240 | window opened on the buffer if such a window exists. |
| 2241 | |
| 2242 | @item |
| 2243 | Selecting a window sets the value of point in its buffer from the |
| 2244 | window's value of point. Conversely, deselecting a window sets the |
| 2245 | window's value of point from that of the buffer. Thus, when you switch |
| 2246 | between windows that display a given buffer, the point value for the |
| 2247 | selected window is in effect in the buffer, while the point values for |
| 2248 | the other windows are stored in those windows. |
| 2249 | |
| 2250 | @item |
| 2251 | As long as the selected window displays the current buffer, the window's |
| 2252 | point and the buffer's point always move together; they remain equal. |
| 2253 | @end itemize |
| 2254 | |
| 2255 | @cindex cursor |
| 2256 | As far as the user is concerned, point is where the cursor is, and |
| 2257 | when the user switches to another buffer, the cursor jumps to the |
| 2258 | position of point in that buffer. |
| 2259 | |
| 2260 | @defun window-point &optional window |
| 2261 | This function returns the current position of point in @var{window}. |
| 2262 | For a nonselected window, this is the value point would have (in that |
| 2263 | window's buffer) if that window were selected. The default for |
| 2264 | @var{window} is the selected window. |
| 2265 | |
| 2266 | When @var{window} is the selected window and its buffer is also the |
| 2267 | current buffer, the value returned is the same as point in that buffer. |
| 2268 | Strictly speaking, it would be more correct to return the ``top-level'' |
| 2269 | value of point, outside of any @code{save-excursion} forms. But that |
| 2270 | value is hard to find. |
| 2271 | @end defun |
| 2272 | |
| 2273 | @defun set-window-point window position |
| 2274 | This function positions point in @var{window} at position |
| 2275 | @var{position} in @var{window}'s buffer. It returns @var{position}. |
| 2276 | |
| 2277 | If @var{window} is selected, and its buffer is current, |
| 2278 | this simply does @code{goto-char}. |
| 2279 | @end defun |
| 2280 | |
| 2281 | @defvar window-point-insertion-type |
| 2282 | This variable specifies the marker insertion type (@pxref{Marker |
| 2283 | Insertion Types}) of @code{window-point}. The default is @code{nil}, |
| 2284 | so @code{window-point} will stay behind text inserted there. |
| 2285 | @end defvar |
| 2286 | |
| 2287 | @node Window Start and End |
| 2288 | @section The Window Start and End Positions |
| 2289 | @cindex window start position |
| 2290 | |
| 2291 | Each window maintains a marker used to keep track of a buffer position |
| 2292 | that specifies where in the buffer display should start. This position |
| 2293 | is called the @dfn{display-start} position of the window (or just the |
| 2294 | @dfn{start}). The character after this position is the one that appears |
| 2295 | at the upper left corner of the window. It is usually, but not |
| 2296 | inevitably, at the beginning of a text line. |
| 2297 | |
| 2298 | After switching windows or buffers, and in some other cases, if the |
| 2299 | window start is in the middle of a line, Emacs adjusts the window |
| 2300 | start to the start of a line. This prevents certain operations from |
| 2301 | leaving the window start at a meaningless point within a line. This |
| 2302 | feature may interfere with testing some Lisp code by executing it |
| 2303 | using the commands of Lisp mode, because they trigger this |
| 2304 | readjustment. To test such code, put it into a command and bind the |
| 2305 | command to a key. |
| 2306 | |
| 2307 | @defun window-start &optional window |
| 2308 | @cindex window top line |
| 2309 | This function returns the display-start position of window |
| 2310 | @var{window}. If @var{window} is @code{nil}, the selected window is |
| 2311 | used. For example, |
| 2312 | |
| 2313 | @example |
| 2314 | @group |
| 2315 | (window-start) |
| 2316 | @result{} 7058 |
| 2317 | @end group |
| 2318 | @end example |
| 2319 | |
| 2320 | When you create a window, or display a different buffer in it, the |
| 2321 | display-start position is set to a display-start position recently used |
| 2322 | for the same buffer, or to @code{point-min} if the buffer doesn't have |
| 2323 | any. |
| 2324 | |
| 2325 | Redisplay updates the window-start position (if you have not specified |
| 2326 | it explicitly since the previous redisplay)---to make sure point appears |
| 2327 | on the screen. Nothing except redisplay automatically changes the |
| 2328 | window-start position; if you move point, do not expect the window-start |
| 2329 | position to change in response until after the next redisplay. |
| 2330 | |
| 2331 | For a realistic example of using @code{window-start}, see the |
| 2332 | description of @code{count-lines}. @xref{Definition of count-lines}. |
| 2333 | @end defun |
| 2334 | |
| 2335 | @cindex window end position |
| 2336 | @defun window-end &optional window update |
| 2337 | This function returns the position where display of its buffer ends in |
| 2338 | @var{window}. The default for @var{window} is the selected window. |
| 2339 | |
| 2340 | Simply changing the buffer text or moving point does not update the |
| 2341 | value that @code{window-end} returns. The value is updated only when |
| 2342 | Emacs redisplays and redisplay completes without being preempted. |
| 2343 | |
| 2344 | If the last redisplay of @var{window} was preempted, and did not finish, |
| 2345 | Emacs does not know the position of the end of display in that window. |
| 2346 | In that case, this function returns @code{nil}. |
| 2347 | |
| 2348 | If @var{update} is non-@code{nil}, @code{window-end} always returns an |
| 2349 | up-to-date value for where display ends, based on the current |
| 2350 | @code{window-start} value. If a previously saved value of that position |
| 2351 | is still valid, @code{window-end} returns that value; otherwise it |
| 2352 | computes the correct value by scanning the buffer text. |
| 2353 | |
| 2354 | Even if @var{update} is non-@code{nil}, @code{window-end} does not |
| 2355 | attempt to scroll the display if point has moved off the screen, the |
| 2356 | way real redisplay would do. It does not alter the |
| 2357 | @code{window-start} value. In effect, it reports where the displayed |
| 2358 | text will end if scrolling is not required. |
| 2359 | @end defun |
| 2360 | |
| 2361 | @defun set-window-start window position &optional noforce |
| 2362 | This function sets the display-start position of @var{window} to |
| 2363 | @var{position} in @var{window}'s buffer. It returns @var{position}. |
| 2364 | |
| 2365 | The display routines insist that the position of point be visible when a |
| 2366 | buffer is displayed. Normally, they change the display-start position |
| 2367 | (that is, scroll the window) whenever necessary to make point visible. |
| 2368 | However, if you specify the start position with this function using |
| 2369 | @code{nil} for @var{noforce}, it means you want display to start at |
| 2370 | @var{position} even if that would put the location of point off the |
| 2371 | screen. If this does place point off screen, the display routines move |
| 2372 | point to the left margin on the middle line in the window. |
| 2373 | |
| 2374 | For example, if point @w{is 1} and you set the start of the window |
| 2375 | @w{to 37}, the start of the next line, point will be ``above'' the top |
| 2376 | of the window. The display routines will automatically move point if |
| 2377 | it is still 1 when redisplay occurs. Here is an example: |
| 2378 | |
| 2379 | @example |
| 2380 | @group |
| 2381 | ;; @r{Here is what @samp{foo} looks like before executing} |
| 2382 | ;; @r{the @code{set-window-start} expression.} |
| 2383 | @end group |
| 2384 | |
| 2385 | @group |
| 2386 | ---------- Buffer: foo ---------- |
| 2387 | @point{}This is the contents of buffer foo. |
| 2388 | 2 |
| 2389 | 3 |
| 2390 | 4 |
| 2391 | 5 |
| 2392 | 6 |
| 2393 | ---------- Buffer: foo ---------- |
| 2394 | @end group |
| 2395 | |
| 2396 | @group |
| 2397 | (set-window-start |
| 2398 | (selected-window) |
| 2399 | (save-excursion |
| 2400 | (goto-char 1) |
| 2401 | (forward-line 1) |
| 2402 | (point))) |
| 2403 | @result{} 37 |
| 2404 | @end group |
| 2405 | |
| 2406 | @group |
| 2407 | ;; @r{Here is what @samp{foo} looks like after executing} |
| 2408 | ;; @r{the @code{set-window-start} expression.} |
| 2409 | ---------- Buffer: foo ---------- |
| 2410 | 2 |
| 2411 | 3 |
| 2412 | @point{}4 |
| 2413 | 5 |
| 2414 | 6 |
| 2415 | ---------- Buffer: foo ---------- |
| 2416 | @end group |
| 2417 | @end example |
| 2418 | |
| 2419 | If @var{noforce} is non-@code{nil}, and @var{position} would place point |
| 2420 | off screen at the next redisplay, then redisplay computes a new window-start |
| 2421 | position that works well with point, and thus @var{position} is not used. |
| 2422 | @end defun |
| 2423 | |
| 2424 | @defun pos-visible-in-window-p &optional position window partially |
| 2425 | This function returns non-@code{nil} if @var{position} is within the |
| 2426 | range of text currently visible on the screen in @var{window}. It |
| 2427 | returns @code{nil} if @var{position} is scrolled vertically out of view. |
| 2428 | Locations that are partially obscured are not considered visible unless |
| 2429 | @var{partially} is non-@code{nil}. The argument @var{position} defaults |
| 2430 | to the current position of point in @var{window}; @var{window}, to the |
| 2431 | selected window. If @var{position} is @code{t}, that means to check the |
| 2432 | last visible position in @var{window}. |
| 2433 | |
| 2434 | This function considers only vertical scrolling. If @var{position} is |
| 2435 | out of view only because @var{window} has been scrolled horizontally, |
| 2436 | @code{pos-visible-in-window-p} returns non-@code{nil} anyway. |
| 2437 | @xref{Horizontal Scrolling}. |
| 2438 | |
| 2439 | If @var{position} is visible, @code{pos-visible-in-window-p} returns |
| 2440 | @code{t} if @var{partially} is @code{nil}; if @var{partially} is |
| 2441 | non-@code{nil}, and the character following @var{position} is fully |
| 2442 | visible, it returns a list of the form @code{(@var{x} @var{y})}, where |
| 2443 | @var{x} and @var{y} are the pixel coordinates relative to the top left |
| 2444 | corner of the window; otherwise it returns an extended list of the form |
| 2445 | @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, |
| 2446 | where @var{rtop} and @var{rbot} specify the number of off-window pixels |
| 2447 | at the top and bottom of the row at @var{position}, @var{rowh} specifies |
| 2448 | the visible height of that row, and @var{vpos} specifies the vertical |
| 2449 | position (zero-based row number) of that row. |
| 2450 | |
| 2451 | Here is an example: |
| 2452 | |
| 2453 | @example |
| 2454 | @group |
| 2455 | ;; @r{If point is off the screen now, recenter it now.} |
| 2456 | (or (pos-visible-in-window-p |
| 2457 | (point) (selected-window)) |
| 2458 | (recenter 0)) |
| 2459 | @end group |
| 2460 | @end example |
| 2461 | @end defun |
| 2462 | |
| 2463 | @defun window-line-height &optional line window |
| 2464 | This function returns the height of text line @var{line} in |
| 2465 | @var{window}. If @var{line} is one of @code{header-line} or |
| 2466 | @code{mode-line}, @code{window-line-height} returns information about |
| 2467 | the corresponding line of the window. Otherwise, @var{line} is a text |
| 2468 | line number starting from 0. A negative number counts from the end of |
| 2469 | the window. The default for @var{line} is the current line in |
| 2470 | @var{window}; the default for @var{window} is the selected window. |
| 2471 | |
| 2472 | If the display is not up to date, @code{window-line-height} returns |
| 2473 | @code{nil}. In that case, @code{pos-visible-in-window-p} may be used |
| 2474 | to obtain related information. |
| 2475 | |
| 2476 | If there is no line corresponding to the specified @var{line}, |
| 2477 | @code{window-line-height} returns @code{nil}. Otherwise, it returns |
| 2478 | a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, |
| 2479 | where @var{height} is the height in pixels of the visible part of the |
| 2480 | line, @var{vpos} and @var{ypos} are the vertical position in lines and |
| 2481 | pixels of the line relative to the top of the first text line, and |
| 2482 | @var{offbot} is the number of off-window pixels at the bottom of the |
| 2483 | text line. If there are off-window pixels at the top of the (first) |
| 2484 | text line, @var{ypos} is negative. |
| 2485 | @end defun |
| 2486 | |
| 2487 | @node Textual Scrolling |
| 2488 | @section Textual Scrolling |
| 2489 | @cindex textual scrolling |
| 2490 | @cindex scrolling textually |
| 2491 | |
| 2492 | @dfn{Textual scrolling} means moving the text up or down through a |
| 2493 | window. It works by changing the window's display-start location. It |
| 2494 | may also change the value of @code{window-point} to keep point on the |
| 2495 | screen (@pxref{Window Point}). |
| 2496 | |
| 2497 | The basic textual scrolling functions are @code{scroll-up} (which |
| 2498 | scrolls forward) and @code{scroll-down} (which scrolls backward). In |
| 2499 | these function names, ``up'' and ``down'' refer to the direction of |
| 2500 | motion of the buffer text relative to the window. Imagine that the |
| 2501 | text is written on a long roll of paper and that the scrolling |
| 2502 | commands move the paper up and down. Thus, if you are looking at the |
| 2503 | middle of a buffer and repeatedly call @code{scroll-down}, you will |
| 2504 | eventually see the beginning of the buffer. |
| 2505 | |
| 2506 | Some people have urged that the opposite convention be used: they |
| 2507 | imagine the window moving over text that remains in place, so that |
| 2508 | ``down'' commands take you to the end of the buffer. This convention |
| 2509 | is consistent with fact that such a command is bound to a key named |
| 2510 | @key{PageDown} on modern keyboards. We have not switched to this |
| 2511 | convention as that is likely to break existing Emacs Lisp code. |
| 2512 | |
| 2513 | Textual scrolling functions (aside from @code{scroll-other-window}) |
| 2514 | have unpredictable results if the current buffer is not the one |
| 2515 | displayed in the selected window. @xref{Current Buffer}. |
| 2516 | |
| 2517 | If the window contains a row taller than the height of the window |
| 2518 | (for example in the presence of a large image), the scroll functions |
| 2519 | will adjust the window's vertical scroll position to scroll the |
| 2520 | partially visible row. Lisp callers can disable this feature by |
| 2521 | binding the variable @code{auto-window-vscroll} to @code{nil} |
| 2522 | (@pxref{Vertical Scrolling}). |
| 2523 | |
| 2524 | @deffn Command scroll-up &optional count |
| 2525 | This function scrolls forward by @var{count} lines in the selected |
| 2526 | window. |
| 2527 | |
| 2528 | If @var{count} is negative, it scrolls backward instead. If |
| 2529 | @var{count} is @code{nil} (or omitted), the distance scrolled is |
| 2530 | @code{next-screen-context-lines} lines less than the height of the |
| 2531 | window's text area. |
| 2532 | |
| 2533 | If the selected window cannot be scrolled any further, this function |
| 2534 | signals an error. Otherwise, it returns @code{nil}. |
| 2535 | @end deffn |
| 2536 | |
| 2537 | @deffn Command scroll-down &optional count |
| 2538 | This function scrolls backward by @var{count} lines in the selected |
| 2539 | window. |
| 2540 | |
| 2541 | If @var{count} is negative, it scrolls forward instead. If |
| 2542 | @var{count} is omitted or @code{nil}, the distance scrolled is |
| 2543 | @code{next-screen-context-lines} lines less than the height of the |
| 2544 | window's text area. |
| 2545 | |
| 2546 | If the selected window cannot be scrolled any further, this function |
| 2547 | signals an error. Otherwise, it returns @code{nil}. |
| 2548 | @end deffn |
| 2549 | |
| 2550 | @deffn Command scroll-up-command &optional count |
| 2551 | This behaves like @code{scroll-up}, except that if the selected window |
| 2552 | cannot be scrolled any further and the value of the variable |
| 2553 | @code{scroll-error-top-bottom} is @code{t}, it tries to move to the |
| 2554 | end of the buffer instead. If point is already there, it signals an |
| 2555 | error. |
| 2556 | @end deffn |
| 2557 | |
| 2558 | @deffn Command scroll-down-command &optional count |
| 2559 | This behaves like @code{scroll-down}, except that if the selected |
| 2560 | window cannot be scrolled any further and the value of the variable |
| 2561 | @code{scroll-error-top-bottom} is @code{t}, it tries to move to the |
| 2562 | beginning of the buffer instead. If point is already there, it |
| 2563 | signals an error. |
| 2564 | @end deffn |
| 2565 | |
| 2566 | @deffn Command scroll-other-window &optional count |
| 2567 | This function scrolls the text in another window upward @var{count} |
| 2568 | lines. Negative values of @var{count}, or @code{nil}, are handled |
| 2569 | as in @code{scroll-up}. |
| 2570 | |
| 2571 | You can specify which buffer to scroll by setting the variable |
| 2572 | @code{other-window-scroll-buffer} to a buffer. If that buffer isn't |
| 2573 | already displayed, @code{scroll-other-window} displays it in some |
| 2574 | window. |
| 2575 | |
| 2576 | When the selected window is the minibuffer, the next window is normally |
| 2577 | the one at the top left corner. You can specify a different window to |
| 2578 | scroll, when the minibuffer is selected, by setting the variable |
| 2579 | @code{minibuffer-scroll-window}. This variable has no effect when any |
| 2580 | other window is selected. When it is non-@code{nil} and the |
| 2581 | minibuffer is selected, it takes precedence over |
| 2582 | @code{other-window-scroll-buffer}. @xref{Definition of |
| 2583 | minibuffer-scroll-window}. |
| 2584 | |
| 2585 | When the minibuffer is active, it is the next window if the selected |
| 2586 | window is the one at the bottom right corner. In this case, |
| 2587 | @code{scroll-other-window} attempts to scroll the minibuffer. If the |
| 2588 | minibuffer contains just one line, it has nowhere to scroll to, so the |
| 2589 | line reappears after the echo area momentarily displays the message |
| 2590 | @samp{Beginning of buffer}. |
| 2591 | @end deffn |
| 2592 | |
| 2593 | @defvar other-window-scroll-buffer |
| 2594 | If this variable is non-@code{nil}, it tells @code{scroll-other-window} |
| 2595 | which buffer's window to scroll. |
| 2596 | @end defvar |
| 2597 | |
| 2598 | @defopt scroll-margin |
| 2599 | This option specifies the size of the scroll margin---a minimum number |
| 2600 | of lines between point and the top or bottom of a window. Whenever |
| 2601 | point gets within this many lines of the top or bottom of the window, |
| 2602 | redisplay scrolls the text automatically (if possible) to move point |
| 2603 | out of the margin, closer to the center of the window. |
| 2604 | @end defopt |
| 2605 | |
| 2606 | @defopt scroll-conservatively |
| 2607 | This variable controls how scrolling is done automatically when point |
| 2608 | moves off the screen (or into the scroll margin). If the value is a |
| 2609 | positive integer @var{n}, then redisplay scrolls the text up to |
| 2610 | @var{n} lines in either direction, if that will bring point back into |
| 2611 | proper view. This behavior is called @dfn{conservative scrolling}. |
| 2612 | Otherwise, scrolling happens in the usual way, under the control of |
| 2613 | other variables such as @code{scroll-up-aggressively} and |
| 2614 | @code{scroll-down-aggressively}. |
| 2615 | |
| 2616 | The default value is zero, which means that conservative scrolling |
| 2617 | never happens. |
| 2618 | @end defopt |
| 2619 | |
| 2620 | @defopt scroll-down-aggressively |
| 2621 | The value of this variable should be either @code{nil} or a fraction |
| 2622 | @var{f} between 0 and 1. If it is a fraction, that specifies where on |
| 2623 | the screen to put point when scrolling down. More precisely, when a |
| 2624 | window scrolls down because point is above the window start, the new |
| 2625 | start position is chosen to put point @var{f} part of the window |
| 2626 | height from the top. The larger @var{f}, the more aggressive the |
| 2627 | scrolling. |
| 2628 | |
| 2629 | A value of @code{nil} is equivalent to .5, since its effect is to center |
| 2630 | point. This variable automatically becomes buffer-local when set in any |
| 2631 | fashion. |
| 2632 | @end defopt |
| 2633 | |
| 2634 | @defopt scroll-up-aggressively |
| 2635 | Likewise, for scrolling up. The value, @var{f}, specifies how far |
| 2636 | point should be placed from the bottom of the window; thus, as with |
| 2637 | @code{scroll-up-aggressively}, a larger value scrolls more aggressively. |
| 2638 | @end defopt |
| 2639 | |
| 2640 | @defopt scroll-step |
| 2641 | This variable is an older variant of @code{scroll-conservatively}. |
| 2642 | The difference is that if its value is @var{n}, that permits scrolling |
| 2643 | only by precisely @var{n} lines, not a smaller number. This feature |
| 2644 | does not work with @code{scroll-margin}. The default value is zero. |
| 2645 | @end defopt |
| 2646 | |
| 2647 | @cindex @code{scroll-command} property |
| 2648 | @defopt scroll-preserve-screen-position |
| 2649 | If this option is @code{t}, whenever a scrolling command moves point |
| 2650 | off-window, Emacs tries to adjust point to keep the cursor at its old |
| 2651 | vertical position in the window, rather than the window edge. |
| 2652 | |
| 2653 | If the value is non-@code{nil} and not @code{t}, Emacs adjusts point |
| 2654 | to keep the cursor at the same vertical position, even if the |
| 2655 | scrolling command didn't move point off-window. |
| 2656 | |
| 2657 | This option affects all scroll commands that have a non-@code{nil} |
| 2658 | @code{scroll-command} symbol property. |
| 2659 | @end defopt |
| 2660 | |
| 2661 | @defopt next-screen-context-lines |
| 2662 | The value of this variable is the number of lines of continuity to |
| 2663 | retain when scrolling by full screens. For example, @code{scroll-up} |
| 2664 | with an argument of @code{nil} scrolls so that this many lines at the |
| 2665 | bottom of the window appear instead at the top. The default value is |
| 2666 | @code{2}. |
| 2667 | @end defopt |
| 2668 | |
| 2669 | @defopt scroll-error-top-bottom |
| 2670 | If this option is @code{nil} (the default), @code{scroll-up-command} |
| 2671 | and @code{scroll-down-command} simply signal an error when no more |
| 2672 | scrolling is possible. |
| 2673 | |
| 2674 | If the value is @code{t}, these commands instead move point to the |
| 2675 | beginning or end of the buffer (depending on scrolling direction); |
| 2676 | only if point is already on that position do they signal an error. |
| 2677 | @end defopt |
| 2678 | |
| 2679 | @deffn Command recenter &optional count |
| 2680 | @cindex centering point |
| 2681 | This function scrolls the text in the selected window so that point is |
| 2682 | displayed at a specified vertical position within the window. It does |
| 2683 | not ``move point'' with respect to the text. |
| 2684 | |
| 2685 | If @var{count} is a non-negative number, that puts the line containing |
| 2686 | point @var{count} lines down from the top of the window. If |
| 2687 | @var{count} is a negative number, then it counts upward from the |
| 2688 | bottom of the window, so that @minus{}1 stands for the last usable |
| 2689 | line in the window. If @var{count} is a non-@code{nil} list, then it |
| 2690 | stands for the line in the middle of the window. |
| 2691 | |
| 2692 | If @var{count} is @code{nil}, @code{recenter} puts the line containing |
| 2693 | point in the middle of the window, then clears and redisplays the entire |
| 2694 | selected frame. |
| 2695 | |
| 2696 | When @code{recenter} is called interactively, @var{count} is the raw |
| 2697 | prefix argument. Thus, typing @kbd{C-u} as the prefix sets the |
| 2698 | @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets |
| 2699 | @var{count} to 4, which positions the current line four lines from the |
| 2700 | top. |
| 2701 | |
| 2702 | With an argument of zero, @code{recenter} positions the current line at |
| 2703 | the top of the window. This action is so handy that some people make a |
| 2704 | separate key binding to do this. For example, |
| 2705 | |
| 2706 | @example |
| 2707 | @group |
| 2708 | (defun line-to-top-of-window () |
| 2709 | "Scroll current line to top of window. |
| 2710 | Replaces three keystroke sequence C-u 0 C-l." |
| 2711 | (interactive) |
| 2712 | (recenter 0)) |
| 2713 | |
| 2714 | (global-set-key [kp-multiply] 'line-to-top-of-window) |
| 2715 | @end group |
| 2716 | @end example |
| 2717 | @end deffn |
| 2718 | |
| 2719 | @node Vertical Scrolling |
| 2720 | @section Vertical Fractional Scrolling |
| 2721 | @cindex vertical fractional scrolling |
| 2722 | @cindex vertical scroll position |
| 2723 | |
| 2724 | @dfn{Vertical fractional scrolling} means shifting text in a window |
| 2725 | up or down by a specified multiple or fraction of a line. Each window |
| 2726 | has a @dfn{vertical scroll position}, which is a number, never less than |
| 2727 | zero. It specifies how far to raise the contents of the window. |
| 2728 | Raising the window contents generally makes all or part of some lines |
| 2729 | disappear off the top, and all or part of some other lines appear at the |
| 2730 | bottom. The usual value is zero. |
| 2731 | |
| 2732 | The vertical scroll position is measured in units of the normal line |
| 2733 | height, which is the height of the default font. Thus, if the value is |
| 2734 | .5, that means the window contents are scrolled up half the normal line |
| 2735 | height. If it is 3.3, that means the window contents are scrolled up |
| 2736 | somewhat over three times the normal line height. |
| 2737 | |
| 2738 | What fraction of a line the vertical scrolling covers, or how many |
| 2739 | lines, depends on what the lines contain. A value of .5 could scroll a |
| 2740 | line whose height is very short off the screen, while a value of 3.3 |
| 2741 | could scroll just part of the way through a tall line or an image. |
| 2742 | |
| 2743 | @defun window-vscroll &optional window pixels-p |
| 2744 | This function returns the current vertical scroll position of |
| 2745 | @var{window}. The default for @var{window} is the selected window. |
| 2746 | If @var{pixels-p} is non-@code{nil}, the return value is measured in |
| 2747 | pixels, rather than in units of the normal line height. |
| 2748 | |
| 2749 | @example |
| 2750 | @group |
| 2751 | (window-vscroll) |
| 2752 | @result{} 0 |
| 2753 | @end group |
| 2754 | @end example |
| 2755 | @end defun |
| 2756 | |
| 2757 | @defun set-window-vscroll window lines &optional pixels-p |
| 2758 | This function sets @var{window}'s vertical scroll position to |
| 2759 | @var{lines}. If @var{window} is @code{nil}, the selected window is |
| 2760 | used. The argument @var{lines} should be zero or positive; if not, it |
| 2761 | is taken as zero. |
| 2762 | |
| 2763 | |
| 2764 | The actual vertical scroll position must always correspond |
| 2765 | to an integral number of pixels, so the value you specify |
| 2766 | is rounded accordingly. |
| 2767 | |
| 2768 | The return value is the result of this rounding. |
| 2769 | |
| 2770 | @example |
| 2771 | @group |
| 2772 | (set-window-vscroll (selected-window) 1.2) |
| 2773 | @result{} 1.13 |
| 2774 | @end group |
| 2775 | @end example |
| 2776 | |
| 2777 | If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of |
| 2778 | pixels. In this case, the return value is @var{lines}. |
| 2779 | @end defun |
| 2780 | |
| 2781 | @defvar auto-window-vscroll |
| 2782 | If this variable is non-@code{nil}, the line-move, scroll-up, and |
| 2783 | scroll-down functions will automatically modify the vertical scroll |
| 2784 | position to scroll through display rows that are taller than the height |
| 2785 | of the window, for example in the presence of large images. |
| 2786 | @end defvar |
| 2787 | |
| 2788 | @node Horizontal Scrolling |
| 2789 | @section Horizontal Scrolling |
| 2790 | @cindex horizontal scrolling |
| 2791 | |
| 2792 | @dfn{Horizontal scrolling} means shifting the image in the window left |
| 2793 | or right by a specified multiple of the normal character width. Each |
| 2794 | window has a @dfn{horizontal scroll position}, which is a number, never |
| 2795 | less than zero. It specifies how far to shift the contents left. |
| 2796 | Shifting the window contents left generally makes all or part of some |
| 2797 | characters disappear off the left, and all or part of some other |
| 2798 | characters appear at the right. The usual value is zero. |
| 2799 | |
| 2800 | The horizontal scroll position is measured in units of the normal |
| 2801 | character width, which is the width of space in the default font. Thus, |
| 2802 | if the value is 5, that means the window contents are scrolled left by 5 |
| 2803 | times the normal character width. How many characters actually |
| 2804 | disappear off to the left depends on their width, and could vary from |
| 2805 | line to line. |
| 2806 | |
| 2807 | Because we read from side to side in the ``inner loop,'' and from top |
| 2808 | to bottom in the ``outer loop,'' the effect of horizontal scrolling is |
| 2809 | not like that of textual or vertical scrolling. Textual scrolling |
| 2810 | involves selection of a portion of text to display, and vertical |
| 2811 | scrolling moves the window contents contiguously; but horizontal |
| 2812 | scrolling causes part of @emph{each line} to go off screen. |
| 2813 | |
| 2814 | Usually, no horizontal scrolling is in effect; then the leftmost |
| 2815 | column is at the left edge of the window. In this state, scrolling to |
| 2816 | the right is meaningless, since there is no data to the left of the edge |
| 2817 | to be revealed by it; so this is not allowed. Scrolling to the left is |
| 2818 | allowed; it scrolls the first columns of text off the edge of the window |
| 2819 | and can reveal additional columns on the right that were truncated |
| 2820 | before. Once a window has a nonzero amount of leftward horizontal |
| 2821 | scrolling, you can scroll it back to the right, but only so far as to |
| 2822 | reduce the net horizontal scroll to zero. There is no limit to how far |
| 2823 | left you can scroll, but eventually all the text will disappear off the |
| 2824 | left edge. |
| 2825 | |
| 2826 | @vindex auto-hscroll-mode |
| 2827 | If @code{auto-hscroll-mode} is set, redisplay automatically alters |
| 2828 | the horizontal scrolling of a window as necessary to ensure that point |
| 2829 | is always visible. However, you can still set the horizontal |
| 2830 | scrolling value explicitly. The value you specify serves as a lower |
| 2831 | bound for automatic scrolling, i.e. automatic scrolling will not |
| 2832 | scroll a window to a column less than the specified one. |
| 2833 | |
| 2834 | @deffn Command scroll-left &optional count set-minimum |
| 2835 | This function scrolls the selected window @var{count} columns to the |
| 2836 | left (or to the right if @var{count} is negative). The default |
| 2837 | for @var{count} is the window width, minus 2. |
| 2838 | |
| 2839 | The return value is the total amount of leftward horizontal scrolling in |
| 2840 | effect after the change---just like the value returned by |
| 2841 | @code{window-hscroll} (below). |
| 2842 | |
| 2843 | Once you scroll a window as far right as it can go, back to its normal |
| 2844 | position where the total leftward scrolling is zero, attempts to scroll |
| 2845 | any farther right have no effect. |
| 2846 | |
| 2847 | If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes |
| 2848 | the lower bound for automatic scrolling; that is, automatic scrolling |
| 2849 | will not scroll a window to a column less than the value returned by |
| 2850 | this function. Interactive calls pass non-@code{nil} for |
| 2851 | @var{set-minimum}. |
| 2852 | @end deffn |
| 2853 | |
| 2854 | @deffn Command scroll-right &optional count set-minimum |
| 2855 | This function scrolls the selected window @var{count} columns to the |
| 2856 | right (or to the left if @var{count} is negative). The default |
| 2857 | for @var{count} is the window width, minus 2. Aside from the direction |
| 2858 | of scrolling, this works just like @code{scroll-left}. |
| 2859 | @end deffn |
| 2860 | |
| 2861 | @defun window-hscroll &optional window |
| 2862 | This function returns the total leftward horizontal scrolling of |
| 2863 | @var{window}---the number of columns by which the text in @var{window} |
| 2864 | is scrolled left past the left margin. The default for |
| 2865 | @var{window} is the selected window. |
| 2866 | |
| 2867 | The return value is never negative. It is zero when no horizontal |
| 2868 | scrolling has been done in @var{window} (which is usually the case). |
| 2869 | |
| 2870 | |
| 2871 | @example |
| 2872 | @group |
| 2873 | (window-hscroll) |
| 2874 | @result{} 0 |
| 2875 | @end group |
| 2876 | @group |
| 2877 | (scroll-left 5) |
| 2878 | @result{} 5 |
| 2879 | @end group |
| 2880 | @group |
| 2881 | (window-hscroll) |
| 2882 | @result{} 5 |
| 2883 | @end group |
| 2884 | @end example |
| 2885 | @end defun |
| 2886 | |
| 2887 | @defun set-window-hscroll window columns |
| 2888 | This function sets horizontal scrolling of @var{window}. The value of |
| 2889 | @var{columns} specifies the amount of scrolling, in terms of columns |
| 2890 | from the left margin. The argument @var{columns} should be zero or |
| 2891 | positive; if not, it is taken as zero. Fractional values of |
| 2892 | @var{columns} are not supported at present. |
| 2893 | |
| 2894 | Note that @code{set-window-hscroll} may appear not to work if you test |
| 2895 | it by evaluating a call with @kbd{M-:} in a simple way. What happens |
| 2896 | is that the function sets the horizontal scroll value and returns, but |
| 2897 | then redisplay adjusts the horizontal scrolling to make point visible, |
| 2898 | and this overrides what the function did. You can observe the |
| 2899 | function's effect if you call it while point is sufficiently far from |
| 2900 | the left margin that it will remain visible. |
| 2901 | |
| 2902 | The value returned is @var{columns}. |
| 2903 | |
| 2904 | @example |
| 2905 | @group |
| 2906 | (set-window-hscroll (selected-window) 10) |
| 2907 | @result{} 10 |
| 2908 | @end group |
| 2909 | @end example |
| 2910 | @end defun |
| 2911 | |
| 2912 | Here is how you can determine whether a given position @var{position} |
| 2913 | is off the screen due to horizontal scrolling: |
| 2914 | |
| 2915 | @example |
| 2916 | @group |
| 2917 | (defun hscroll-on-screen (window position) |
| 2918 | (save-excursion |
| 2919 | (goto-char position) |
| 2920 | (and |
| 2921 | (>= (- (current-column) (window-hscroll window)) 0) |
| 2922 | (< (- (current-column) (window-hscroll window)) |
| 2923 | (window-width window))))) |
| 2924 | @end group |
| 2925 | @end example |
| 2926 | |
| 2927 | @node Coordinates and Windows |
| 2928 | @section Coordinates and Windows |
| 2929 | @cindex frame-relative coordinate |
| 2930 | @cindex coordinate, relative to frame |
| 2931 | @cindex window position |
| 2932 | |
| 2933 | This section describes functions that report the position of a |
| 2934 | window. Most of these functions report positions relative to the |
| 2935 | window's frame. In this case, the coordinate origin @samp{(0,0)} lies |
| 2936 | near the upper left corner of the frame. For technical reasons, on |
| 2937 | graphical displays the origin is not located at the exact corner of |
| 2938 | the graphical window as it appears on the screen. If Emacs is built |
| 2939 | with the GTK+ toolkit, the origin is at the upper left corner of the |
| 2940 | frame area used for displaying Emacs windows, below the title-bar, |
| 2941 | GTK+ menu bar, and tool bar (since these are drawn by the window |
| 2942 | manager and/or GTK+, not by Emacs). But if Emacs is not built with |
| 2943 | GTK+, the origin is at the upper left corner of the tool bar (since in |
| 2944 | this case Emacs itself draws the tool bar). In both cases, the X and |
| 2945 | Y coordinates increase rightward and downward respectively. |
| 2946 | |
| 2947 | Except where noted, X and Y coordinates are reported in integer |
| 2948 | character units, i.e. numbers of lines and columns respectively. On a |
| 2949 | graphical display, each ``line'' and ``column'' corresponds to the |
| 2950 | height and width of a default character specified by the frame's |
| 2951 | default font. |
| 2952 | |
| 2953 | @defun window-edges &optional window |
| 2954 | This function returns a list of the edge coordinates of @var{window}. |
| 2955 | If @var{window} is omitted or @code{nil}, it defaults to the selected |
| 2956 | window. |
| 2957 | |
| 2958 | The return value has the form @code{(@var{left} @var{top} @var{right} |
| 2959 | @var{bottom})}. These list elements are, respectively, the X |
| 2960 | coordinate of the leftmost column occupied by the window, the Y |
| 2961 | coordinate of the topmost row, the X coordinate one column to the |
| 2962 | right of the rightmost column, and the Y coordinate one row down from |
| 2963 | the bottommost row. |
| 2964 | |
| 2965 | Note that these are the actual outer edges of the window, including |
| 2966 | any header line, mode line, scroll bar, fringes, and display margins. |
| 2967 | On a text-only terminal, if the window has a neighbor on its right, |
| 2968 | its right edge includes the separator line between the window and its |
| 2969 | neighbor. |
| 2970 | @end defun |
| 2971 | |
| 2972 | @defun window-inside-edges &optional window |
| 2973 | This function is similar to @code{window-edges}, but the returned edge |
| 2974 | values are for the text area of the window. They exclude any header |
| 2975 | line, mode line, scroll bar, fringes, display margins, and vertical |
| 2976 | separator. |
| 2977 | @end defun |
| 2978 | |
| 2979 | @defun window-top-line &optional window |
| 2980 | This function returns the Y coordinate of the topmost row of |
| 2981 | @var{window}, equivalent to the @var{top} entry in the list returned |
| 2982 | by @code{window-edges}. |
| 2983 | @end defun |
| 2984 | |
| 2985 | @defun window-left-column &optional window |
| 2986 | This function returns the X coordinate of the leftmost column of |
| 2987 | @var{window}, equivalent to the @var{left} entry in the list returned |
| 2988 | by @code{window-edges}. |
| 2989 | @end defun |
| 2990 | |
| 2991 | The following functions can be used to relate a set of |
| 2992 | frame-relative coordinates to a window: |
| 2993 | |
| 2994 | @defun window-at x y &optional frame |
| 2995 | This function returns the live window at the frame-relative |
| 2996 | coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no |
| 2997 | window at that position, the return value is @code{nil}. If |
| 2998 | @var{frame} is omitted or @code{nil}, it defaults to the selected |
| 2999 | frame. |
| 3000 | @end defun |
| 3001 | |
| 3002 | @defun coordinates-in-window-p coordinates window |
| 3003 | This function checks whether a window @var{window} occupies the |
| 3004 | frame-relative coordinates @var{coordinates}, and if so which part of |
| 3005 | the window that is. @var{window} should be a live window. |
| 3006 | @var{coordinates} should be a cons cell of the form @code{(@var{x} |
| 3007 | . @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. |
| 3008 | |
| 3009 | If there is no window at the specified position, the return value is |
| 3010 | @code{nil} . Otherwise, the return value is one of the following: |
| 3011 | |
| 3012 | @table @code |
| 3013 | @item (@var{relx} . @var{rely}) |
| 3014 | The coordinates are inside @var{window}. The numbers @var{relx} and |
| 3015 | @var{rely} are the equivalent window-relative coordinates for the |
| 3016 | specified position, counting from 0 at the top left corner of the |
| 3017 | window. |
| 3018 | |
| 3019 | @item mode-line |
| 3020 | The coordinates are in the mode line of @var{window}. |
| 3021 | |
| 3022 | @item header-line |
| 3023 | The coordinates are in the header line of @var{window}. |
| 3024 | |
| 3025 | @item vertical-line |
| 3026 | The coordinates are in the vertical line between @var{window} and its |
| 3027 | neighbor to the right. This value occurs only if the window doesn't |
| 3028 | have a scroll bar; positions in a scroll bar are considered outside the |
| 3029 | window for these purposes. |
| 3030 | |
| 3031 | @item left-fringe |
| 3032 | @itemx right-fringe |
| 3033 | The coordinates are in the left or right fringe of the window. |
| 3034 | |
| 3035 | @item left-margin |
| 3036 | @itemx right-margin |
| 3037 | The coordinates are in the left or right margin of the window. |
| 3038 | |
| 3039 | @item nil |
| 3040 | The coordinates are not in any part of @var{window}. |
| 3041 | @end table |
| 3042 | |
| 3043 | The function @code{coordinates-in-window-p} does not require a frame as |
| 3044 | argument because it always uses the frame that @var{window} is on. |
| 3045 | @end defun |
| 3046 | |
| 3047 | The following functions return window positions in pixels, rather |
| 3048 | than character units. Though mostly useful on graphical displays, |
| 3049 | they can also be called on text-only terminals, where the screen area |
| 3050 | of each text character is taken to be ``one pixel''. |
| 3051 | |
| 3052 | @defun window-pixel-edges &optional window |
| 3053 | This function returns a list of pixel coordinates for the edges of |
| 3054 | @var{window}. If @var{window} is omitted or @code{nil}, it defaults |
| 3055 | to the selected window. |
| 3056 | |
| 3057 | The return value has the form @code{(@var{left} @var{top} @var{right} |
| 3058 | @var{bottom})}. The list elements are, respectively, the X pixel |
| 3059 | coordinate of the left window edge, the Y pixel coordinate of the top |
| 3060 | edge, one more than the X pixel coordinate of the right edge, and one |
| 3061 | more than the Y pixel coordinate of the bottom edge. |
| 3062 | @end defun |
| 3063 | |
| 3064 | @defun window-inside-pixel-edges &optional window |
| 3065 | This function is like @code{window-pixel-edges}, except that it |
| 3066 | returns the pixel coordinates for the edges of the window's text area, |
| 3067 | rather than the pixel coordinates for the edges of the window itself. |
| 3068 | @var{window} must specify a live window. |
| 3069 | @end defun |
| 3070 | |
| 3071 | The following functions return window positions in pixels, relative |
| 3072 | to the display screen rather than the frame: |
| 3073 | |
| 3074 | @defun window-absolute-pixel-edges &optional window |
| 3075 | This function is like @code{window-pixel-edges}, except that it |
| 3076 | returns the edge pixel coordinates relative to the top left corner of |
| 3077 | the display screen. |
| 3078 | @end defun |
| 3079 | |
| 3080 | @defun window-inside-absolute-pixel-edges &optional window |
| 3081 | This function is like @code{window-inside-pixel-edges}, except that it |
| 3082 | returns the edge pixel coordinates relative to the top left corner of |
| 3083 | the display screen. @var{window} must specify a live window. |
| 3084 | @end defun |
| 3085 | |
| 3086 | @node Window Configurations |
| 3087 | @section Window Configurations |
| 3088 | @cindex window configurations |
| 3089 | @cindex saving window information |
| 3090 | |
| 3091 | A @dfn{window configuration} records the entire layout of one |
| 3092 | frame---all windows, their sizes, which buffers they contain, how those |
| 3093 | buffers are scrolled, and their values of point and the mark; also their |
| 3094 | fringes, margins, and scroll bar settings. It also includes the value |
| 3095 | of @code{minibuffer-scroll-window}. As a special exception, the window |
| 3096 | configuration does not record the value of point in the selected window |
| 3097 | for the current buffer. |
| 3098 | |
| 3099 | You can bring back an entire frame layout by restoring a previously |
| 3100 | saved window configuration. If you want to record the layout of all |
| 3101 | frames instead of just one, use a frame configuration instead of a |
| 3102 | window configuration; see @ref{Frame Configurations}. |
| 3103 | |
| 3104 | @defun current-window-configuration &optional frame |
| 3105 | This function returns a new object representing @var{frame}'s current |
| 3106 | window configuration. The default for @var{frame} is the selected |
| 3107 | frame. This function saves copies of window parameters listed by the |
| 3108 | variable @code{window-persistent-parameters}, see @ref{Window |
| 3109 | Parameters} for details. |
| 3110 | @end defun |
| 3111 | |
| 3112 | @defun set-window-configuration configuration |
| 3113 | This function restores the configuration of windows and buffers as |
| 3114 | specified by @var{configuration}, for the frame that @var{configuration} |
| 3115 | was created for. |
| 3116 | |
| 3117 | The argument @var{configuration} must be a value that was previously |
| 3118 | returned by @code{current-window-configuration}. The configuration is |
| 3119 | restored in the frame from which @var{configuration} was made, whether |
| 3120 | that frame is selected or not. This always counts as a window size |
| 3121 | change and triggers execution of the @code{window-size-change-functions} |
| 3122 | (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't |
| 3123 | know how to tell whether the new configuration actually differs from the |
| 3124 | old one. |
| 3125 | |
| 3126 | If the frame which @var{configuration} was saved from is dead, all this |
| 3127 | function does is restore the three variables @code{window-min-height}, |
| 3128 | @code{window-min-width} and @code{minibuffer-scroll-window}. In this |
| 3129 | case, the function returns @code{nil}. Otherwise, it returns @code{t}. |
| 3130 | |
| 3131 | Here is a way of using this function to get the same effect |
| 3132 | as @code{save-window-excursion}: |
| 3133 | |
| 3134 | @example |
| 3135 | @group |
| 3136 | (let ((config (current-window-configuration))) |
| 3137 | (unwind-protect |
| 3138 | (progn (split-window-below nil) |
| 3139 | @dots{}) |
| 3140 | (set-window-configuration config))) |
| 3141 | @end group |
| 3142 | @end example |
| 3143 | @end defun |
| 3144 | |
| 3145 | @defspec save-window-excursion forms@dots{} |
| 3146 | This special form records the window configuration, executes @var{forms} |
| 3147 | in sequence, then restores the earlier window configuration. The window |
| 3148 | configuration includes, for each window, the value of point and the |
| 3149 | portion of the buffer that is visible. It also includes the choice of |
| 3150 | selected window. However, it does not include the value of point in |
| 3151 | the current buffer; use @code{save-excursion} also, if you wish to |
| 3152 | preserve that. |
| 3153 | |
| 3154 | Don't use this construct when @code{save-selected-window} is sufficient. |
| 3155 | |
| 3156 | Exit from @code{save-window-excursion} always triggers execution of |
| 3157 | @code{window-size-change-functions}. (It doesn't know how to tell |
| 3158 | whether the restored configuration actually differs from the one in |
| 3159 | effect at the end of the @var{forms}.) |
| 3160 | |
| 3161 | The return value is the value of the final form in @var{forms}. |
| 3162 | For example: |
| 3163 | |
| 3164 | @example |
| 3165 | @group |
| 3166 | (split-window) |
| 3167 | @result{} #<window 25 on control.texi> |
| 3168 | @end group |
| 3169 | @group |
| 3170 | (setq w (selected-window)) |
| 3171 | @result{} #<window 19 on control.texi> |
| 3172 | @end group |
| 3173 | @group |
| 3174 | (save-window-excursion |
| 3175 | (delete-other-windows w) |
| 3176 | (switch-to-buffer "foo") |
| 3177 | 'do-something) |
| 3178 | @result{} do-something |
| 3179 | ;; @r{The screen is now split again.} |
| 3180 | @end group |
| 3181 | @end example |
| 3182 | @end defspec |
| 3183 | |
| 3184 | @defun window-configuration-p object |
| 3185 | This function returns @code{t} if @var{object} is a window configuration. |
| 3186 | @end defun |
| 3187 | |
| 3188 | @defun compare-window-configurations config1 config2 |
| 3189 | This function compares two window configurations as regards the |
| 3190 | structure of windows, but ignores the values of point and mark and the |
| 3191 | saved scrolling positions---it can return @code{t} even if those |
| 3192 | aspects differ. |
| 3193 | |
| 3194 | The function @code{equal} can also compare two window configurations; it |
| 3195 | regards configurations as unequal if they differ in any respect, even a |
| 3196 | saved point or mark. |
| 3197 | @end defun |
| 3198 | |
| 3199 | @defun window-configuration-frame config |
| 3200 | This function returns the frame for which the window configuration |
| 3201 | @var{config} was made. |
| 3202 | @end defun |
| 3203 | |
| 3204 | Other primitives to look inside of window configurations would make |
| 3205 | sense, but are not implemented because we did not need them. See the |
| 3206 | file @file{winner.el} for some more operations on windows |
| 3207 | configurations. |
| 3208 | |
| 3209 | The objects returned by @code{current-window-configuration} die |
| 3210 | together with the Emacs process. In order to store a window |
| 3211 | configuration on disk and read it back in another Emacs session, the |
| 3212 | functions described next can be used. These functions are also useful |
| 3213 | to clone the state of a frame into an arbitrary live window |
| 3214 | (@code{set-window-configuration} effectively clones the windows of a |
| 3215 | frame into the root window of that very frame only). |
| 3216 | |
| 3217 | @defun window-state-get &optional window ignore |
| 3218 | This function returns the state of @var{window} as a Lisp object. The |
| 3219 | argument @var{window} can be any window and defaults to the root window |
| 3220 | of the selected frame. |
| 3221 | |
| 3222 | If the optional argument @var{ignore} is non-@code{nil}, this means to |
| 3223 | not use markers for sampling positions like @code{window-point} or |
| 3224 | @code{window-start}. This argument should be non-@code{nil} when the |
| 3225 | state shall be written on disk and read back in another session. |
| 3226 | |
| 3227 | The variable @code{window-persistent-parameters} specifies whether and |
| 3228 | which window parameters are saved by this function, see @ref{Window |
| 3229 | Parameters} for details. |
| 3230 | @end defun |
| 3231 | |
| 3232 | The value returned by @code{window-state-get} can be converted, using |
| 3233 | one of the functions defined by Desktop Save Mode (@pxref{Desktop Save |
| 3234 | Mode}), to an object that can be written to a file. Such objects can be |
| 3235 | read back and converted to a Lisp object representing the state of the |
| 3236 | window. That Lisp object can be used as argument for the following |
| 3237 | function in order to restore the state window in another window. |
| 3238 | |
| 3239 | @defun window-state-put state &optional window ignore |
| 3240 | This function puts the window state @var{state} into @var{window}. The |
| 3241 | argument @var{state} should be the state of a window returned by an |
| 3242 | earlier invocation of @code{window-state-get}, see above. The optional |
| 3243 | argument @var{window} must specify a live window and defaults to the |
| 3244 | selected one. |
| 3245 | |
| 3246 | The optional argument @var{ignore} non-@code{nil} means to ignore |
| 3247 | minimum window sizes and fixed size restrictions. If @var{ignore} |
| 3248 | equals @code{safe}, this means windows can get as small as one line |
| 3249 | and/or two columns. |
| 3250 | @end defun |
| 3251 | |
| 3252 | |
| 3253 | @node Window Parameters |
| 3254 | @section Window Parameters |
| 3255 | @cindex window parameters |
| 3256 | |
| 3257 | This section describes how window parameters can be used to associate |
| 3258 | additional information with windows. |
| 3259 | |
| 3260 | @defun window-parameter window parameter |
| 3261 | This function returns @var{window}'s value for @var{parameter}. The |
| 3262 | default for @var{window} is the selected window. If @var{window} has no |
| 3263 | setting for @var{parameter}, this function returns @code{nil}. |
| 3264 | @end defun |
| 3265 | |
| 3266 | @defun window-parameters &optional window |
| 3267 | This function returns all parameters of @var{window} and their values. |
| 3268 | The default for @var{window} is the selected window. The return value, |
| 3269 | if non-@code{nil} is an association list whose elements have the form |
| 3270 | @code{(@var{parameter} . @var{value})}. |
| 3271 | @end defun |
| 3272 | |
| 3273 | @defun set-window-parameter window parameter value |
| 3274 | This function sets @var{window}'s value of @var{parameter} to |
| 3275 | @var{value} and returns @var{value}. The default for @var{window} |
| 3276 | is the selected window. |
| 3277 | @end defun |
| 3278 | |
| 3279 | By default, functions saving and restoring window configurations or the |
| 3280 | states of windows (@pxref{Window Configurations}) do not care about |
| 3281 | window parameters. This means, that when you change the value of a |
| 3282 | parameter within the body of a @code{save-window-excursion}, the |
| 3283 | previous value is not restored upon exit of that macro. It also means |
| 3284 | that when you clone via @code{window-state-put} a window state saved |
| 3285 | earlier by @code{window-state-get}, the cloned windows come up with no |
| 3286 | parameters at all. The following variable allows to override the |
| 3287 | standard behavior. |
| 3288 | |
| 3289 | @defvar window-persistent-parameters |
| 3290 | This variable is an alist specifying which parameters get saved by |
| 3291 | @code{current-window-configuration} and @code{window-state-get} and |
| 3292 | subsequently restored by @code{set-window-configuration} and |
| 3293 | @code{window-state-put}, see @ref{Window Configurations}. |
| 3294 | |
| 3295 | The @sc{car} of each entry of this alist is the symbol specifying the |
| 3296 | parameter. The @sc{cdr} must be one of the following: |
| 3297 | |
| 3298 | @table @asis |
| 3299 | @item @code{state} |
| 3300 | This value means the parameter is saved by @code{window-state-get} |
| 3301 | provided its @var{ignore} argument is @code{nil}. The function |
| 3302 | @code{current-window-configuration} does not save this parameter. |
| 3303 | |
| 3304 | @item @code{nil} |
| 3305 | This value specifies that the parameter is saved by |
| 3306 | @code{current-window-configuration} and, provided its @var{ignore} |
| 3307 | argument is @code{nil}, by @code{window-state-get}. |
| 3308 | |
| 3309 | @item @code{t} |
| 3310 | This means that the parameter is saved unconditionally by both |
| 3311 | @code{current-window-configuration} and @code{window-state-get}. This |
| 3312 | value should not be used for parameters whose values do not have a read |
| 3313 | syntax. Otherwise, invoking @code{window-state-put} in another session |
| 3314 | may fail with an @code{invalid-read-syntax} error. |
| 3315 | @end table |
| 3316 | |
| 3317 | Parameters that have been saved are restored to their previous values by |
| 3318 | @code{set-window-configuration} respectively are installed by |
| 3319 | @code{window-state-put}. Parameters that have not been saved are left |
| 3320 | alone by @code{set-window-configuration} respectively are not installed |
| 3321 | by @code{window-state-put}. |
| 3322 | @end defvar |
| 3323 | |
| 3324 | Some functions, notably @code{delete-window}, |
| 3325 | @code{delete-other-windows} and @code{split-window} may behave specially |
| 3326 | when their @var{window} argument has a parameter set. You can override |
| 3327 | such special behavior by binding the following variable to a |
| 3328 | non-@code{nil} value: |
| 3329 | |
| 3330 | @defvar ignore-window-parameters |
| 3331 | If this variable is non-@code{nil}, some standard functions do not |
| 3332 | process window parameters. The functions currently affected by this are |
| 3333 | @code{split-window}, @code{delete-window}, @code{delete-other-windows} |
| 3334 | and @code{other-window}. |
| 3335 | |
| 3336 | An application can bind this variable to a non-@code{nil} value around |
| 3337 | calls to these functions. If it does so, the application is fully |
| 3338 | responsible for correctly assigning the parameters of all involved |
| 3339 | windows when exiting that function. |
| 3340 | @end defvar |
| 3341 | |
| 3342 | The following parameters are currently used by the window management |
| 3343 | code: |
| 3344 | |
| 3345 | @table @asis |
| 3346 | @item @code{delete-window} |
| 3347 | This parameter affects the execution of @code{delete-window} |
| 3348 | (@pxref{Deleting Windows}). |
| 3349 | |
| 3350 | @item @code{delete-other-windows} |
| 3351 | This parameter affects the execution of @code{delete-other-windows} |
| 3352 | (@pxref{Deleting Windows}). |
| 3353 | |
| 3354 | @item @code{split-window} |
| 3355 | This parameter affects the execution of @code{split-window} |
| 3356 | (@pxref{Splitting Windows}). |
| 3357 | |
| 3358 | @item @code{other-window} |
| 3359 | This parameter affects the execution of @code{other-window} |
| 3360 | (@pxref{Cyclic Window Ordering}). |
| 3361 | |
| 3362 | @item @code{no-other-window} |
| 3363 | This parameter marks the window as not selectable by @code{other-window} |
| 3364 | (@pxref{Cyclic Window Ordering}). |
| 3365 | |
| 3366 | @item @code{clone-of} |
| 3367 | This parameter specifies the window this one has been cloned from and is |
| 3368 | installed by @code{window-state-get}, see @ref{Window Configurations}. |
| 3369 | |
| 3370 | @item @code{quit-restore} |
| 3371 | This parameter tells how to proceed with a window when the buffer it |
| 3372 | shows is no more needed. It is installed by the buffer display |
| 3373 | functions (@pxref{Choosing Window}) and consulted by the function |
| 3374 | @code{quit-window} (@pxref{Quitting Windows}). |
| 3375 | @end table |
| 3376 | |
| 3377 | In addition, the parameters @code{window-atom} and @code{window-side} |
| 3378 | are reserved and should not be used by applications. |
| 3379 | |
| 3380 | |
| 3381 | @node Window Hooks |
| 3382 | @section Hooks for Window Scrolling and Changes |
| 3383 | @cindex hooks for window operations |
| 3384 | |
| 3385 | This section describes how a Lisp program can take action whenever a |
| 3386 | window displays a different part of its buffer or a different buffer. |
| 3387 | There are three actions that can change this: scrolling the window, |
| 3388 | switching buffers in the window, and changing the size of the window. |
| 3389 | The first two actions run @code{window-scroll-functions}; the last runs |
| 3390 | @code{window-size-change-functions}. |
| 3391 | |
| 3392 | @defvar window-scroll-functions |
| 3393 | This variable holds a list of functions that Emacs should call before |
| 3394 | redisplaying a window with scrolling. Displaying a different buffer in |
| 3395 | the window also runs these functions. |
| 3396 | |
| 3397 | This variable is not a normal hook, because each function is called with |
| 3398 | two arguments: the window, and its new display-start position. |
| 3399 | |
| 3400 | These functions must be careful in using @code{window-end} |
| 3401 | (@pxref{Window Start and End}); if you need an up-to-date value, you |
| 3402 | must use the @var{update} argument to ensure you get it. |
| 3403 | |
| 3404 | @strong{Warning:} don't use this feature to alter the way the window |
| 3405 | is scrolled. It's not designed for that, and such use probably won't |
| 3406 | work. |
| 3407 | @end defvar |
| 3408 | |
| 3409 | @defvar window-size-change-functions |
| 3410 | This variable holds a list of functions to be called if the size of any |
| 3411 | window changes for any reason. The functions are called just once per |
| 3412 | redisplay, and just once for each frame on which size changes have |
| 3413 | occurred. |
| 3414 | |
| 3415 | Each function receives the frame as its sole argument. There is no |
| 3416 | direct way to find out which windows on that frame have changed size, or |
| 3417 | precisely how. However, if a size-change function records, at each |
| 3418 | call, the existing windows and their sizes, it can also compare the |
| 3419 | present sizes and the previous sizes. |
| 3420 | |
| 3421 | Creating or deleting windows counts as a size change, and therefore |
| 3422 | causes these functions to be called. Changing the frame size also |
| 3423 | counts, because it changes the sizes of the existing windows. |
| 3424 | |
| 3425 | It is not a good idea to use @code{save-window-excursion} (@pxref{Window |
| 3426 | Configurations}) in these functions, because that always counts as a |
| 3427 | size change, and it would cause these functions to be called over and |
| 3428 | over. In most cases, @code{save-selected-window} (@pxref{Selecting |
| 3429 | Windows}) is what you need here. |
| 3430 | @end defvar |
| 3431 | |
| 3432 | @defvar window-configuration-change-hook |
| 3433 | A normal hook that is run every time you change the window configuration |
| 3434 | of an existing frame. This includes splitting or deleting windows, |
| 3435 | changing the sizes of windows, or displaying a different buffer in a |
| 3436 | window. |
| 3437 | |
| 3438 | The buffer-local part of this hook is run once per each window on the |
| 3439 | affected frame, with the relevant window selected and its buffer |
| 3440 | current. The global part is run once for the modified frame, with that |
| 3441 | frame selected. |
| 3442 | @end defvar |
| 3443 | |
| 3444 | In addition, you can use @code{jit-lock-register} to register a Font |
| 3445 | Lock fontification function, which will be called whenever parts of a |
| 3446 | buffer are (re)fontified because a window was scrolled or its size |
| 3447 | changed. @xref{Other Font Lock Variables}. |