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