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