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