Mercurial > emacs
comparison lispref/windows.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 23a1cea22d13 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c -*-texinfo-*- | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | 2 @c This is part of the GNU Emacs Lisp Reference Manual. |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, |
4 @c Free Software Foundation, Inc. | 4 @c 2004, 2005 Free Software Foundation, Inc. |
5 @c See the file elisp.texi for copying conditions. | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/windows | 6 @setfilename ../info/windows |
7 @node Windows, Frames, Buffers, Top | 7 @node Windows, Frames, Buffers, Top |
8 @chapter Windows | 8 @chapter Windows |
9 | 9 |
16 * Splitting Windows:: Splitting one window into two windows. | 16 * Splitting Windows:: Splitting one window into two windows. |
17 * Deleting Windows:: Deleting a window gives its space to other windows. | 17 * Deleting Windows:: Deleting a window gives its space to other windows. |
18 * Selecting Windows:: The selected window is the one that you edit in. | 18 * Selecting Windows:: The selected window is the one that you edit in. |
19 * Cyclic Window Ordering:: Moving around the existing windows. | 19 * Cyclic Window Ordering:: Moving around the existing windows. |
20 * Buffers and Windows:: Each window displays the contents of a buffer. | 20 * Buffers and Windows:: Each window displays the contents of a buffer. |
21 * Displaying Buffers:: Higher-lever functions for displaying a buffer | 21 * Displaying Buffers:: Higher-level functions for displaying a buffer |
22 and choosing a window for it. | 22 and choosing a window for it. |
23 * Choosing Window:: How to choose a window for displaying a buffer. | 23 * Choosing Window:: How to choose a window for displaying a buffer. |
24 * Window Point:: Each window has its own location of point. | 24 * Window Point:: Each window has its own location of point. |
25 * Window Start:: The display-start position controls which text | 25 * Window Start:: The display-start position controls which text |
26 is on-screen in the window. | 26 is on-screen in the window. |
28 * Vertical Scrolling:: Moving the contents up and down on the window. | 28 * Vertical Scrolling:: Moving the contents up and down on the window. |
29 * Horizontal Scrolling:: Moving the contents sideways on the window. | 29 * Horizontal Scrolling:: Moving the contents sideways on the window. |
30 * Size of Window:: Accessing the size of a window. | 30 * Size of Window:: Accessing the size of a window. |
31 * Resizing Windows:: Changing the size of a window. | 31 * Resizing Windows:: Changing the size of a window. |
32 * Coordinates and Windows:: Converting coordinates to windows. | 32 * Coordinates and Windows:: Converting coordinates to windows. |
33 * Window Tree:: The layout and sizes of all windows in a frame. | |
33 * Window Configurations:: Saving and restoring the state of the screen. | 34 * Window Configurations:: Saving and restoring the state of the screen. |
34 * Window Hooks:: Hooks for scrolling, window size changes, | 35 * Window Hooks:: Hooks for scrolling, window size changes, |
35 redisplay going past a certain point, | 36 redisplay going past a certain point, |
36 or window configuration changes. | 37 or window configuration changes. |
37 @end menu | 38 @end menu |
51 one window, but you can subdivide it vertically or horizontally into | 52 one window, but you can subdivide it vertically or horizontally into |
52 multiple nonoverlapping Emacs windows. | 53 multiple nonoverlapping Emacs windows. |
53 | 54 |
54 In each frame, at any time, one and only one window is designated as | 55 In each frame, at any time, one and only one window is designated as |
55 @dfn{selected within the frame}. The frame's cursor appears in that | 56 @dfn{selected within the frame}. The frame's cursor appears in that |
56 window. At any time, one frame is the selected frame; and the window | 57 window, but the other windows have ``non-selected'' cursors, normally |
57 selected within that frame is @dfn{the selected window}. The selected | 58 less visible. At any time, one frame is the selected frame; and the |
58 window's buffer is usually the current buffer (except when | 59 window selected within that frame is @dfn{the selected window}. The |
60 selected window's buffer is usually the current buffer (except when | |
59 @code{set-buffer} has been used). @xref{Current Buffer}. | 61 @code{set-buffer} has been used). @xref{Current Buffer}. |
62 | |
63 @defvar cursor-in-non-selected-windows | |
64 If this variable is @code{nil}, Emacs displays only one cursor, | |
65 in the selected window. Other windows have no cursor at all. | |
66 @end defvar | |
60 | 67 |
61 For practical purposes, a window exists only while it is displayed in | 68 For practical purposes, a window exists only while it is displayed in |
62 a frame. Once removed from the frame, the window is effectively deleted | 69 a frame. Once removed from the frame, the window is effectively deleted |
63 and should not be used, @emph{even though there may still be references | 70 and should not be used, @emph{even though there may still be references |
64 to it} from other Lisp objects. Restoring a saved window configuration | 71 to it} from other Lisp objects. Restoring a saved window configuration |
95 @item | 102 @item |
96 the mark | 103 the mark |
97 | 104 |
98 @item | 105 @item |
99 how recently the window was selected | 106 how recently the window was selected |
107 | |
108 @item | |
109 fringe settings | |
110 | |
111 @item | |
112 display margins | |
113 | |
114 @item | |
115 scroll-bar settings | |
100 @end itemize | 116 @end itemize |
101 | 117 |
102 @cindex multiple windows | 118 @cindex multiple windows |
103 Users create multiple windows so they can look at several buffers at | 119 Users create multiple windows so they can look at several buffers at |
104 once. Lisp libraries use multiple windows for a variety of reasons, but | 120 once. Lisp libraries use multiple windows for a variety of reasons, but |
250 column 0 column 80 | 266 column 0 column 80 |
251 @end group | 267 @end group |
252 @end smallexample | 268 @end smallexample |
253 | 269 |
254 Normally, Emacs indicates the border between two side-by-side windows | 270 Normally, Emacs indicates the border between two side-by-side windows |
255 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|} | 271 with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|} |
256 characters. The display table can specify alternative border | 272 characters. The display table can specify alternative border |
257 characters; see @ref{Display Tables}. | 273 characters; see @ref{Display Tables}. |
258 @end deffn | 274 @end deffn |
259 | 275 |
260 @deffn Command split-window-vertically &optional size | 276 @deffn Command split-window-vertically &optional size |
261 This function splits the selected window into two windows, one above the | 277 This function splits the selected window into two windows, one above the |
262 other, leaving the upper of the two windows selected, with @var{size} | 278 other, leaving the upper of the two windows selected, with @var{size} |
263 lines. (If @var{size} is negative, then the lower of the two windows | 279 lines. (If @var{size} is negative, then the lower of the two windows |
264 gets @minus{} @var{size} lines and the upper window gets the rest, but | 280 gets @minus{} @var{size} lines and the upper window gets the rest, but |
265 the upper window is still the one selected.) | 281 the upper window is still the one selected.) However, if |
282 @code{split-window-keep-point} (see below) is @code{nil}, then either | |
283 window can be selected. | |
284 | |
285 In other respects, this function is similar to @code{split-window}. | |
286 In particular, the upper window is the original one and the return | |
287 value is the new, lower window. | |
266 @end deffn | 288 @end deffn |
289 | |
290 @defopt split-window-keep-point | |
291 If this variable is non-@code{nil} (the default), then | |
292 @code{split-window-vertically} behaves as described above. | |
293 | |
294 If it is @code{nil}, then @code{split-window-vertically} adjusts point | |
295 in each of the two windows to avoid scrolling. (This is useful on | |
296 slow terminals.) It selects whichever window contains the screen line | |
297 that point was previously on. | |
298 | |
299 This variable only affects the behavior of @code{split-window-vertically}. | |
300 It has no effect on the other functions described here. | |
301 @end defopt | |
267 | 302 |
268 @deffn Command split-window-horizontally &optional size | 303 @deffn Command split-window-horizontally &optional size |
269 This function splits the selected window into two windows | 304 This function splits the selected window into two windows |
270 side-by-side, leaving the selected window with @var{size} columns. | 305 side-by-side, leaving the selected window on the left with @var{size} |
306 columns. If @var{size} is negative, the rightmost window gets | |
307 @minus{} @var{size} columns, but the leftmost window still remains | |
308 selected. | |
271 | 309 |
272 This function is basically an interface to @code{split-window}. | 310 This function is basically an interface to @code{split-window}. |
273 You could define a simplified version of the function like this: | 311 You could define a simplified version of the function like this: |
274 | 312 |
275 @smallexample | 313 @smallexample |
289 | 327 |
290 @defun one-window-p &optional no-mini all-frames | 328 @defun one-window-p &optional no-mini all-frames |
291 This function returns non-@code{nil} if there is only one window. The | 329 This function returns non-@code{nil} if there is only one window. The |
292 argument @var{no-mini}, if non-@code{nil}, means don't count the | 330 argument @var{no-mini}, if non-@code{nil}, means don't count the |
293 minibuffer even if it is active; otherwise, the minibuffer window is | 331 minibuffer even if it is active; otherwise, the minibuffer window is |
294 included, if active, in the total number of windows, which is compared | 332 counted when it is active. |
295 against one. | |
296 | 333 |
297 The argument @var{all-frames} specifies which frames to consider. Here | 334 The argument @var{all-frames} specifies which frames to consider. Here |
298 are the possible values and their meanings: | 335 are the possible values and their meanings: |
299 | 336 |
300 @table @asis | 337 @table @asis |
353 @code{nil}, then the selected window is used by default. | 390 @code{nil}, then the selected window is used by default. |
354 | 391 |
355 The return value is @code{nil}. | 392 The return value is @code{nil}. |
356 @end deffn | 393 @end deffn |
357 | 394 |
358 @deffn Command delete-windows-on buffer &optional frame | 395 @deffn Command delete-windows-on buffer-or-name &optional frame |
359 This function deletes all windows showing @var{buffer}. If there are | 396 This function deletes all windows showing @var{buffer-or-name}. If |
360 no windows showing @var{buffer}, it does nothing. | 397 there are no windows showing @var{buffer-or-name}, it does nothing. |
398 @var{buffer-or-name} must be a buffer or the name of an existing | |
399 buffer. | |
361 | 400 |
362 @code{delete-windows-on} operates frame by frame. If a frame has | 401 @code{delete-windows-on} operates frame by frame. If a frame has |
363 several windows showing different buffers, then those showing | 402 several windows showing different buffers, then those showing |
364 @var{buffer} are removed, and the others expand to fill the space. If | 403 @var{buffer-or-name} are removed, and the others expand to fill the |
365 all windows in some frame are showing @var{buffer} (including the case | 404 space. If all windows in some frame are showing @var{buffer-or-name} |
366 where there is only one window), then the frame reverts to having a | 405 (including the case where there is only one window), then the frame |
367 single window showing another buffer chosen with @code{other-buffer}. | 406 winds up with a single window showing another buffer chosen with |
368 @xref{The Buffer List}. | 407 @code{other-buffer}. @xref{The Buffer List}. |
369 | 408 |
370 The argument @var{frame} controls which frames to operate on. This | 409 The argument @var{frame} controls which frames to operate on. This |
371 function does not use it in quite the same way as the other functions | 410 function does not use it in quite the same way as the other functions |
372 which scan all windows; specifically, the values @code{t} and @code{nil} | 411 which scan all windows; specifically, the values @code{t} and @code{nil} |
373 have the opposite of their meanings in other functions. Here are the | 412 have the opposite of their meanings in other functions. Here are the |
399 @defun selected-window | 438 @defun selected-window |
400 This function returns the selected window. This is the window in | 439 This function returns the selected window. This is the window in |
401 which the cursor appears and to which many commands apply. | 440 which the cursor appears and to which many commands apply. |
402 @end defun | 441 @end defun |
403 | 442 |
404 @defun select-window window | 443 @defun select-window window &optional norecord |
405 This function makes @var{window} the selected window. The cursor then | 444 This function makes @var{window} the selected window. The cursor then |
406 appears in @var{window} (on redisplay). The buffer being displayed in | 445 appears in @var{window} (on redisplay). Unless @var{window} was |
407 @var{window} is immediately designated the current buffer. | 446 already selected, @code{select-window} makes @var{window}'s buffer the |
447 current buffer. | |
448 | |
449 Normally @var{window}'s selected buffer is moved to the front of the | |
450 buffer list, but if @var{norecord} is non-@code{nil}, the buffer list | |
451 order is unchanged. | |
408 | 452 |
409 The return value is @var{window}. | 453 The return value is @var{window}. |
410 | 454 |
411 @example | 455 @example |
412 @group | 456 @group |
416 @end group | 460 @end group |
417 @end example | 461 @end example |
418 @end defun | 462 @end defun |
419 | 463 |
420 @defmac save-selected-window forms@dots{} | 464 @defmac save-selected-window forms@dots{} |
421 This macro records the selected window, executes @var{forms} | 465 This macro records the selected frame, as well as the selected window |
422 in sequence, then restores the earlier selected window (unless that | 466 of each frame, executes @var{forms} in sequence, then restores the |
423 window is no longer alive). | 467 earlier selected frame and windows. It also saves and restores the |
424 | 468 current buffer. It returns the value of the last form in @var{forms}. |
425 This macro does not save or restore anything about the sizes, arrangement | 469 |
426 or contents of windows; therefore, if the @var{forms} change them, | 470 This macro does not save or restore anything about the sizes, |
427 the change persists. | 471 arrangement or contents of windows; therefore, if the @var{forms} |
428 | 472 change them, the change persists. If the previously selected window |
429 Each frame, at any time, has a window selected within the frame. This | 473 of some frame is no longer live at the time of exit from @var{forms}, |
430 macro saves only @emph{the} selected window; it does not save anything | 474 that frame's selected window is left alone. If the previously |
431 about other frames. If the @var{forms} select some other frame and | 475 selected window is no longer live, then whatever window is selected at |
432 alter the window selected within it, the change persists. | 476 the end of @var{forms} remains selected. |
477 @end defmac | |
478 | |
479 @defmac with-selected-window window forms@dots{} | |
480 This macro selects @var{window} (without changing the buffer list), | |
481 executes @var{forms} in sequence, then restores the previously | |
482 selected window and current buffer. It is just like | |
483 @code{save-selected-window}, except that it explicitly selects | |
484 @var{window}, also without altering the buffer list sequence. | |
433 @end defmac | 485 @end defmac |
434 | 486 |
435 @cindex finding windows | 487 @cindex finding windows |
436 The following functions choose one of the windows on the screen, | 488 The following functions choose one of the windows on the screen, |
437 offering various criteria for the choice. | 489 offering various criteria for the choice. |
438 | 490 |
439 @defun get-lru-window &optional frame | 491 @defun get-lru-window &optional frame dedicated |
440 This function returns the window least recently ``used'' (that is, | 492 This function returns the window least recently ``used'' (that is, |
441 selected). The selected window is always the most recently used window. | 493 selected). If any full-width windows are present, it only considers |
494 these. The selected window is always the most recently used window. | |
442 | 495 |
443 The selected window can be the least recently used window if it is the | 496 The selected window can be the least recently used window if it is the |
444 only window. A newly created window becomes the least recently used | 497 only window. A newly created window becomes the least recently used |
445 window until it is selected. A minibuffer window is never a candidate. | 498 window until it is selected. A minibuffer window is never a |
499 candidate. Dedicated windows are never candidates unless the | |
500 @var{dedicated} argument is non-@code{nil}, so if all | |
501 existing windows are dedicated, the value is @code{nil}. | |
446 | 502 |
447 The argument @var{frame} controls which windows are considered. | 503 The argument @var{frame} controls which windows are considered. |
448 | 504 |
449 @itemize @bullet | 505 @itemize @bullet |
450 @item | 506 @item |
458 @item | 514 @item |
459 If it is a frame, consider windows on that frame. | 515 If it is a frame, consider windows on that frame. |
460 @end itemize | 516 @end itemize |
461 @end defun | 517 @end defun |
462 | 518 |
463 @defun get-largest-window &optional frame | 519 @defun get-largest-window &optional frame dedicated |
464 This function returns the window with the largest area (height times | 520 This function returns the window with the largest area (height times |
465 width). If there are no side-by-side windows, then this is the window | 521 width). If there are no side-by-side windows, then this is the window |
466 with the most lines. A minibuffer window is never a candidate. | 522 with the most lines. A minibuffer window is never a candidate. |
467 | 523 Dedicated windows are never candidates unless the |
468 If there are two windows of the same size, then the function returns | 524 @var{dedicated} argument is non-@code{nil}, so if all existing windows |
469 the window that is first in the cyclic ordering of windows (see | 525 are dedicated, the value is @code{nil}. |
470 following section), starting from the selected window. | 526 |
527 If there are two candidate windows of the same size, this function | |
528 prefers the one that comes first in the cyclic ordering of windows | |
529 (see following section), starting from the selected window. | |
471 | 530 |
472 The argument @var{frame} controls which set of windows to | 531 The argument @var{frame} controls which set of windows to |
473 consider. See @code{get-lru-window}, above. | 532 consider. See @code{get-lru-window}, above. |
474 @end defun | 533 @end defun |
475 | 534 |
476 @cindex window that satisfies a predicate | 535 @cindex window that satisfies a predicate |
477 @cindex conditional selection of windows | 536 @cindex conditional selection of windows |
478 @defun get-window-with-predicate predicate &optional minibuf all-frames default | 537 @defun get-window-with-predicate predicate &optional minibuf all-frames default |
479 This function returns a window satisfying @var{predicate}. It cycles | 538 This function returns a window satisfying @var{predicate}. It cycles |
480 through all visible windows using @code{walk-windows} (@pxref{Cyclic | 539 through all visible windows using @code{walk-windows} (@pxref{Cyclic |
481 Window Ordering}), calling @var{predicate} on each one one of them | 540 Window Ordering}), calling @var{predicate} on each one of them |
482 with that window as its argument. The function returns the first | 541 with that window as its argument. The function returns the first |
483 window for which @var{predicate} returns a non-@code{nil} value; if | 542 window for which @var{predicate} returns a non-@code{nil} value; if |
484 that never happens, it returns @var{default}. | 543 that never happens, it returns @var{default}. |
485 | 544 |
486 The optional arguments @var{minibuf} and @var{all-frames} specify the | 545 The optional arguments @var{minibuf} and @var{all-frames} specify the |
536 are the possible values and their meanings: | 595 are the possible values and their meanings: |
537 | 596 |
538 @table @asis | 597 @table @asis |
539 @item @code{nil} | 598 @item @code{nil} |
540 Consider all the windows in @var{window}'s frame, plus the minibuffer | 599 Consider all the windows in @var{window}'s frame, plus the minibuffer |
541 used by that frame even if it lies in some other frame. | 600 used by that frame even if it lies in some other frame. If the |
601 minibuffer counts (as determined by @var{minibuf}), then all windows on | |
602 all frames that share that minibuffer count too. | |
542 | 603 |
543 @item @code{t} | 604 @item @code{t} |
544 Consider all windows in all existing frames. | 605 Consider all windows in all existing frames. |
545 | 606 |
546 @item @code{visible} | 607 @item @code{visible} |
547 Consider all windows in all visible frames. (To get useful results, you | 608 Consider all windows in all visible frames. (To get useful results, you |
548 must ensure @var{window} is in a visible frame.) | 609 must ensure @var{window} is in a visible frame.) |
549 | 610 |
550 @item 0 | 611 @item 0 |
551 Consider all windows in all visible or iconified frames. | 612 Consider all windows in all visible or iconified frames. |
613 | |
614 @item a frame | |
615 Consider all windows on that frame. | |
552 | 616 |
553 @item anything else | 617 @item anything else |
554 Consider precisely the windows in @var{window}'s frame, and no others. | 618 Consider precisely the windows in @var{window}'s frame, and no others. |
555 @end table | 619 @end table |
556 | 620 |
591 In an interactive call, @var{count} is the numeric prefix argument. | 655 In an interactive call, @var{count} is the numeric prefix argument. |
592 @end deffn | 656 @end deffn |
593 | 657 |
594 @c Emacs 19 feature | 658 @c Emacs 19 feature |
595 @defun walk-windows proc &optional minibuf all-frames | 659 @defun walk-windows proc &optional minibuf all-frames |
596 This function cycles through all windows, calling @code{proc} | 660 This function cycles through all windows. It calls the function |
597 once for each window with the window as its sole argument. | 661 @code{proc} once for each window, with the window as its sole |
662 argument. | |
598 | 663 |
599 The optional arguments @var{minibuf} and @var{all-frames} specify the | 664 The optional arguments @var{minibuf} and @var{all-frames} specify the |
600 set of windows to include in the scan. See @code{next-window}, above, | 665 set of windows to include in the scan. See @code{next-window}, above, |
601 for details. | 666 for details. |
602 @end defun | 667 @end defun |
603 | 668 |
604 @defun window-list &optional frame minibuf window | 669 @defun window-list &optional frame minibuf window |
605 This function returns a list of the windows on @var{frame}, starting | 670 This function returns a list of the windows on @var{frame}, starting |
606 with @var{window}. If @var{frame} is @code{nil} or omitted, the | 671 with @var{window}. If @var{frame} is @code{nil} or omitted, |
607 selected frame is used instead; if @var{window} is @code{nil} or | 672 @code{window-list} uses the selected frame instead; if @var{window} is |
608 omitted, the selected window is used instead. | 673 @code{nil} or omitted, it uses the selected window. |
609 | 674 |
610 The value of @var{minibuf} determines if the minibuffer window will be | 675 The value of @var{minibuf} determines if the minibuffer window is |
611 included in the result list. If @var{minibuf} is @code{t}, the | 676 included in the result list. If @var{minibuf} is @code{t}, the result |
612 minibuffer window will be included, even if it isn't active. If | 677 always includes the minibuffer window. If @var{minibuf} is @code{nil} |
613 @var{minibuf} is @code{nil} or omitted, the minibuffer window will | 678 or omitted, that includes the minibuffer window if it is active. If |
614 only be included in the list if it is active. If @var{minibuf} is | 679 @var{minibuf} is neither @code{nil} nor @code{t}, the result never |
615 neither @code{nil} nor @code{t}, the minibuffer window is not | 680 includes the minibuffer window. |
616 included, whether or not it is active. | |
617 @end defun | 681 @end defun |
618 | 682 |
619 @node Buffers and Windows | 683 @node Buffers and Windows |
620 @section Buffers and Windows | 684 @section Buffers and Windows |
621 @cindex examining windows | 685 @cindex examining windows |
633 related functions that find a window to use and specify a buffer for it. | 697 related functions that find a window to use and specify a buffer for it. |
634 The functions described there are easier to use than these, but they | 698 The functions described there are easier to use than these, but they |
635 employ heuristics in choosing or creating a window; use these functions | 699 employ heuristics in choosing or creating a window; use these functions |
636 when you need complete control. | 700 when you need complete control. |
637 | 701 |
638 @defun set-window-buffer window buffer-or-name | 702 @defun set-window-buffer window buffer-or-name &optional keep-margins |
639 This function makes @var{window} display @var{buffer-or-name} as its | 703 This function makes @var{window} display @var{buffer-or-name} as its |
640 contents. It returns @code{nil}. This is the fundamental primitive | 704 contents. It returns @code{nil}. @var{buffer-or-name} must be a |
641 for changing which buffer is displayed in a window, and all ways | 705 buffer, or the name of an existing buffer. This is the fundamental |
642 of doing that call this function. | 706 primitive for changing which buffer is displayed in a window, and all |
707 ways of doing that call this function. | |
643 | 708 |
644 @example | 709 @example |
645 @group | 710 @group |
646 (set-window-buffer (selected-window) "foo") | 711 (set-window-buffer (selected-window) "foo") |
647 @result{} nil | 712 @result{} nil |
648 @end group | 713 @end group |
649 @end example | 714 @end example |
650 @end defun | 715 |
716 Normally, displaying @var{buffer} in @var{window} resets the window's | |
717 display margins, fringe widths, scroll bar settings, and position | |
718 based on the local variables of @var{buffer}. However, if | |
719 @var{keep-margins} is non-@code{nil}, the display margins and fringe | |
720 widths of @var{window} remain unchanged. @xref{Fringes}. | |
721 @end defun | |
722 | |
723 @defvar buffer-display-count | |
724 This buffer-local variable records the number of times a buffer is | |
725 displayed in a window. It is incremented each time | |
726 @code{set-window-buffer} is called for the buffer. | |
727 @end defvar | |
651 | 728 |
652 @defun window-buffer &optional window | 729 @defun window-buffer &optional window |
653 This function returns the buffer that @var{window} is displaying. If | 730 This function returns the buffer that @var{window} is displaying. If |
654 @var{window} is omitted, this function returns the buffer for the | 731 @var{window} is omitted, this function returns the buffer for the |
655 selected window. | 732 selected window. |
692 The two optional arguments work like the optional arguments of | 769 The two optional arguments work like the optional arguments of |
693 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} | 770 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} |
694 like the single optional argument of @code{get-buffer-window}. Perhaps | 771 like the single optional argument of @code{get-buffer-window}. Perhaps |
695 we should change @code{get-buffer-window} in the future to make it | 772 we should change @code{get-buffer-window} in the future to make it |
696 compatible with the other functions. | 773 compatible with the other functions. |
697 | |
698 The argument @var{all-frames} controls which windows to consider. | |
699 | |
700 @itemize @bullet | |
701 @item | |
702 If it is @code{nil}, consider windows on the selected frame. | |
703 @item | |
704 If it is @code{t}, consider windows on all frames. | |
705 @item | |
706 If it is @code{visible}, consider windows on all visible frames. | |
707 @item | |
708 If it is 0, consider windows on all visible or iconified frames. | |
709 @item | |
710 If it is a frame, consider windows on that frame. | |
711 @end itemize | |
712 @end defun | 774 @end defun |
713 | 775 |
714 @defvar buffer-display-time | 776 @defvar buffer-display-time |
715 This variable records the time at which a buffer was last made visible | 777 This variable records the time at which a buffer was last made visible |
716 in a window. It is always local in each buffer; each time | 778 in a window. It is always local in each buffer; each time |
756 @xref{Current Buffer}. | 818 @xref{Current Buffer}. |
757 | 819 |
758 If @var{buffer-or-name} does not identify an existing buffer, then a new | 820 If @var{buffer-or-name} does not identify an existing buffer, then a new |
759 buffer by that name is created. The major mode for the new buffer is | 821 buffer by that name is created. The major mode for the new buffer is |
760 set according to the variable @code{default-major-mode}. @xref{Auto | 822 set according to the variable @code{default-major-mode}. @xref{Auto |
761 Major Mode}. | 823 Major Mode}. If @var{buffer-or-name} is @code{nil}, |
824 @code{switch-to-buffer} chooses a buffer using @code{other-buffer}. | |
762 | 825 |
763 Normally the specified buffer is put at the front of the buffer list | 826 Normally the specified buffer is put at the front of the buffer list |
764 (both the selected frame's buffer list and the frame-independent buffer | 827 (both the selected frame's buffer list and the frame-independent buffer |
765 list). This affects the operation of @code{other-buffer}. However, if | 828 list). This affects the operation of @code{other-buffer}. However, if |
766 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer | 829 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer |
769 The @code{switch-to-buffer} function is often used interactively, as | 832 The @code{switch-to-buffer} function is often used interactively, as |
770 the binding of @kbd{C-x b}. It is also used frequently in programs. It | 833 the binding of @kbd{C-x b}. It is also used frequently in programs. It |
771 returns the buffer that it switched to. | 834 returns the buffer that it switched to. |
772 @end deffn | 835 @end deffn |
773 | 836 |
837 The next two functions are similar to @code{switch-to-buffer}, except | |
838 for the described features. | |
839 | |
774 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord | 840 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord |
775 This function makes @var{buffer-or-name} the current buffer and | 841 This function makes @var{buffer-or-name} the current buffer and |
776 displays it in a window not currently selected. It then selects that | 842 displays it in a window not currently selected. It then selects that |
777 window. The handling of the buffer is the same as in | 843 window. The handling of the buffer is the same as in |
778 @code{switch-to-buffer}. | 844 @code{switch-to-buffer}. |
790 @defun pop-to-buffer buffer-or-name &optional other-window norecord | 856 @defun pop-to-buffer buffer-or-name &optional other-window norecord |
791 This function makes @var{buffer-or-name} the current buffer and | 857 This function makes @var{buffer-or-name} the current buffer and |
792 switches to it in some window, preferably not the window previously | 858 switches to it in some window, preferably not the window previously |
793 selected. The ``popped-to'' window becomes the selected window within | 859 selected. The ``popped-to'' window becomes the selected window within |
794 its frame. The return value is the buffer that was switched to. | 860 its frame. The return value is the buffer that was switched to. |
861 If @var{buffer-or-name} is @code{nil}, that means to choose some | |
862 other buffer, but you don't specify which. | |
795 | 863 |
796 If the variable @code{pop-up-frames} is non-@code{nil}, | 864 If the variable @code{pop-up-frames} is non-@code{nil}, |
797 @code{pop-to-buffer} looks for a window in any visible frame already | 865 @code{pop-to-buffer} looks for a window in any visible frame already |
798 displaying the buffer; if there is one, it returns that window and makes | 866 displaying the buffer; if there is one, it returns that window and makes |
799 it be selected within its frame. If there is none, it creates a new | 867 it be selected within its frame. If there is none, it creates a new |
826 | 894 |
827 This function updates the buffer list just like @code{switch-to-buffer} | 895 This function updates the buffer list just like @code{switch-to-buffer} |
828 unless @var{norecord} is non-@code{nil}. | 896 unless @var{norecord} is non-@code{nil}. |
829 @end defun | 897 @end defun |
830 | 898 |
831 @deffn Command replace-buffer-in-windows buffer | 899 @deffn Command replace-buffer-in-windows buffer-or-name |
832 This function replaces @var{buffer} with some other buffer in all | 900 This function replaces @var{buffer-or-name} with some other buffer in all |
833 windows displaying it. The other buffer used is chosen with | 901 windows displaying it. It chooses the other buffer with |
834 @code{other-buffer}. In the usual applications of this function, you | 902 @code{other-buffer}. In the usual applications of this function, you |
835 don't care which other buffer is used; you just want to make sure that | 903 don't care which other buffer is used; you just want to make sure that |
836 @var{buffer} is no longer displayed. | 904 @var{buffer-or-name} is no longer displayed. |
837 | 905 |
838 This function returns @code{nil}. | 906 This function returns @code{nil}. |
839 @end deffn | 907 @end deffn |
840 | 908 |
841 @node Choosing Window | 909 @node Choosing Window |
848 | 916 |
849 @deffn Command display-buffer buffer-or-name &optional not-this-window frame | 917 @deffn Command display-buffer buffer-or-name &optional not-this-window frame |
850 This command makes @var{buffer-or-name} appear in some window, like | 918 This command makes @var{buffer-or-name} appear in some window, like |
851 @code{pop-to-buffer}, but it does not select that window and does not | 919 @code{pop-to-buffer}, but it does not select that window and does not |
852 make the buffer current. The identity of the selected window is | 920 make the buffer current. The identity of the selected window is |
853 unaltered by this function. | 921 unaltered by this function. @var{buffer-or-name} must be a buffer, or |
922 the name of an existing buffer. | |
854 | 923 |
855 If @var{not-this-window} is non-@code{nil}, it means to display the | 924 If @var{not-this-window} is non-@code{nil}, it means to display the |
856 specified buffer in a window other than the selected one, even if it is | 925 specified buffer in a window other than the selected one, even if it is |
857 already on display in the selected window. This can cause the buffer to | 926 already on display in the selected window. This can cause the buffer to |
858 appear in two windows at once. Otherwise, if @var{buffer-or-name} is | 927 appear in two windows at once. Otherwise, if @var{buffer-or-name} is |
869 values of @var{frame}: | 938 values of @var{frame}: |
870 | 939 |
871 @itemize @bullet | 940 @itemize @bullet |
872 @item | 941 @item |
873 If it is @code{nil}, consider windows on the selected frame. | 942 If it is @code{nil}, consider windows on the selected frame. |
943 (Actually, the last non-minibuffer frame.) | |
874 @item | 944 @item |
875 If it is @code{t}, consider windows on all frames. | 945 If it is @code{t}, consider windows on all frames. |
876 @item | 946 @item |
877 If it is @code{visible}, consider windows on all visible frames. | 947 If it is @code{visible}, consider windows on all visible frames. |
878 @item | 948 @item |
933 | 1003 |
934 @xref{Frames}, for more information. | 1004 @xref{Frames}, for more information. |
935 @end defopt | 1005 @end defopt |
936 | 1006 |
937 @c Emacs 19 feature | 1007 @c Emacs 19 feature |
938 @defvar pop-up-frame-function | 1008 @defopt pop-up-frame-function |
939 This variable specifies how to make a new frame if @code{pop-up-frames} | 1009 This variable specifies how to make a new frame if @code{pop-up-frames} |
940 is non-@code{nil}. | 1010 is non-@code{nil}. |
941 | 1011 |
942 Its value should be a function of no arguments. When | 1012 Its value should be a function of no arguments. When |
943 @code{display-buffer} makes a new frame, it does so by calling that | 1013 @code{display-buffer} makes a new frame, it does so by calling that |
944 function, which should return a frame. The default value of the | 1014 function, which should return a frame. The default value of the |
945 variable is a function that creates a frame using parameters from | 1015 variable is a function that creates a frame using parameters from |
946 @code{pop-up-frame-alist}. | 1016 @code{pop-up-frame-alist}. |
947 @end defvar | 1017 @end defopt |
948 | 1018 |
949 @defopt pop-up-frame-alist | 1019 @defopt pop-up-frame-alist |
950 This variable holds an alist specifying frame parameters used when | 1020 This variable holds an alist specifying frame parameters used when |
951 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for | 1021 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for |
952 more information about frame parameters. | 1022 more information about frame parameters. |
958 buffer specially. | 1028 buffer specially. |
959 | 1029 |
960 By default, special display means to give the buffer a dedicated frame. | 1030 By default, special display means to give the buffer a dedicated frame. |
961 | 1031 |
962 If an element is a list, instead of a string, then the @sc{car} of the | 1032 If an element is a list, instead of a string, then the @sc{car} of the |
963 list is the buffer name, and the rest of the list says how to create the | 1033 list is the buffer name, and the rest of the list says how to create |
964 frame. There are two possibilities for the rest of the list. It can be | 1034 the frame. There are two possibilities for the rest of the list (its |
965 an alist, specifying frame parameters, or it can contain a function and | 1035 @sc{cdr}). It can be an alist, specifying frame parameters, or it can |
966 arguments to give to it. (The function's first argument is always the | 1036 contain a function and arguments to give to it. (The function's first |
967 buffer to be displayed; the arguments from the list come after that.) | 1037 argument is always the buffer to be displayed; the arguments from the |
1038 list come after that.) | |
1039 | |
1040 For example: | |
1041 | |
1042 @example | |
1043 (("myfile" (minibuffer) (menu-bar-lines . 0))) | |
1044 @end example | |
1045 | |
1046 @noindent | |
1047 specifies to display a buffer named @samp{myfile} in a dedicated frame | |
1048 with specified @code{minibuffer} and @code{menu-bar-lines} parameters. | |
1049 | |
1050 The list of frame parameters can also use the phony frame parameters | |
1051 @code{same-frame} and @code{same-window}. If the specified frame | |
1052 parameters include @code{(same-window . @var{value})} and @var{value} | |
1053 is non-@code{nil}, that means to display the buffer in the current | |
1054 selected window. Otherwise, if they include @code{(same-frame . | |
1055 @var{value})} and @var{value} is non-@code{nil}, that means to display | |
1056 the buffer in a new window in the currently selected frame. | |
968 @end defopt | 1057 @end defopt |
969 | 1058 |
970 @defopt special-display-regexps | 1059 @defopt special-display-regexps |
971 A list of regular expressions that specify buffers that should be | 1060 A list of regular expressions that specify buffers that should be |
972 displayed specially. If the buffer's name matches any of the regular | 1061 displayed specially. If the buffer's name matches any of the regular |
978 If an element is a list, instead of a string, then the @sc{car} of the | 1067 If an element is a list, instead of a string, then the @sc{car} of the |
979 list is the regular expression, and the rest of the list says how to | 1068 list is the regular expression, and the rest of the list says how to |
980 create the frame. See above, under @code{special-display-buffer-names}. | 1069 create the frame. See above, under @code{special-display-buffer-names}. |
981 @end defopt | 1070 @end defopt |
982 | 1071 |
1072 @defun special-display-p buffer-name | |
1073 This function returns non-@code{nil} if displaying a buffer | |
1074 named @var{buffer-name} with @code{display-buffer} would | |
1075 create a special frame. The value is @code{t} if it would | |
1076 use the default frame parameters, or else the specified list | |
1077 of frame parameters. | |
1078 @end defun | |
1079 | |
983 @defvar special-display-function | 1080 @defvar special-display-function |
984 This variable holds the function to call to display a buffer specially. | 1081 This variable holds the function to call to display a buffer specially. |
985 It receives the buffer as an argument, and should return the window in | 1082 It receives the buffer as an argument, and should return the window in |
986 which it is displayed. | 1083 which it is displayed. |
987 | 1084 |
988 The default value of this variable is | 1085 The default value of this variable is |
989 @code{special-display-popup-frame}. | 1086 @code{special-display-popup-frame}. |
990 @end defvar | 1087 @end defvar |
991 | 1088 |
992 @defun special-display-popup-frame buffer &rest args | 1089 @defun special-display-popup-frame buffer &optional args |
993 This function makes @var{buffer} visible in a frame of its own. If | 1090 This function makes @var{buffer} visible in a frame of its own. If |
994 @var{buffer} is already displayed in a window in some frame, it makes | 1091 @var{buffer} is already displayed in a window in some frame, it makes |
995 the frame visible and raises it, to use that window. Otherwise, it | 1092 the frame visible and raises it, to use that window. Otherwise, it |
996 creates a frame that will be dedicated to @var{buffer}. | 1093 creates a frame that will be dedicated to @var{buffer}. This |
1094 function returns the window it used. | |
997 | 1095 |
998 If @var{args} is an alist, it specifies frame parameters for the new | 1096 If @var{args} is an alist, it specifies frame parameters for the new |
999 frame. | 1097 frame. |
1000 | 1098 |
1001 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car | 1099 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car |
1008 variables in your init file, before @var{buffer} was created, then | 1106 variables in your init file, before @var{buffer} was created, then |
1009 presumably the window was previously made by this function. | 1107 presumably the window was previously made by this function. |
1010 @end defun | 1108 @end defun |
1011 | 1109 |
1012 @defopt special-display-frame-alist | 1110 @defopt special-display-frame-alist |
1111 @anchor{Definition of special-display-frame-alist} | |
1013 This variable holds frame parameters for | 1112 This variable holds frame parameters for |
1014 @code{special-display-popup-frame} to use when it creates a frame. | 1113 @code{special-display-popup-frame} to use when it creates a frame. |
1015 @end defopt | 1114 @end defopt |
1016 | 1115 |
1017 @defopt same-window-buffer-names | 1116 @defopt same-window-buffer-names |
1026 displayed in the selected window. If the buffer's name matches any of | 1125 displayed in the selected window. If the buffer's name matches any of |
1027 the regular expressions in this list, @code{display-buffer} handles the | 1126 the regular expressions in this list, @code{display-buffer} handles the |
1028 buffer by switching to it in the selected window. | 1127 buffer by switching to it in the selected window. |
1029 @end defopt | 1128 @end defopt |
1030 | 1129 |
1130 @defun same-window-p buffer-name | |
1131 This function returns @code{t} if displaying a buffer | |
1132 named @var{buffer-name} with @code{display-buffer} would | |
1133 put it in the selected window. | |
1134 @end defun | |
1135 | |
1031 @c Emacs 19 feature | 1136 @c Emacs 19 feature |
1032 @defvar display-buffer-function | 1137 @defvar display-buffer-function |
1033 This variable is the most flexible way to customize the behavior of | 1138 This variable is the most flexible way to customize the behavior of |
1034 @code{display-buffer}. If it is non-@code{nil}, it should be a function | 1139 @code{display-buffer}. If it is non-@code{nil}, it should be a function |
1035 that @code{display-buffer} calls to do the work. The function should | 1140 that @code{display-buffer} calls to do the work. The function should |
1036 accept two arguments, the same two arguments that @code{display-buffer} | 1141 accept two arguments, the first two arguments that @code{display-buffer} |
1037 received. It should choose or create a window, display the specified | 1142 received. It should choose or create a window, display the specified |
1038 buffer, and then return the window. | 1143 buffer in it, and then return the window. |
1039 | 1144 |
1040 This hook takes precedence over all the other options and hooks | 1145 This hook takes precedence over all the other options and hooks |
1041 described above. | 1146 described above. |
1042 @end defvar | 1147 @end defvar |
1043 | 1148 |
1046 A window can be marked as ``dedicated'' to its buffer. Then | 1151 A window can be marked as ``dedicated'' to its buffer. Then |
1047 @code{display-buffer} will not try to use that window to display any | 1152 @code{display-buffer} will not try to use that window to display any |
1048 other buffer. | 1153 other buffer. |
1049 | 1154 |
1050 @defun window-dedicated-p window | 1155 @defun window-dedicated-p window |
1051 This function returns @code{t} if @var{window} is marked as dedicated; | 1156 This function returns non-@code{nil} if @var{window} is marked as |
1052 otherwise @code{nil}. | 1157 dedicated; otherwise @code{nil}. |
1053 @end defun | 1158 @end defun |
1054 | 1159 |
1055 @defun set-window-dedicated-p window flag | 1160 @defun set-window-dedicated-p window flag |
1056 This function marks @var{window} as dedicated if @var{flag} is | 1161 This function marks @var{window} as dedicated if @var{flag} is |
1057 non-@code{nil}, and nondedicated otherwise. | 1162 non-@code{nil}, and nondedicated otherwise. |
1083 the other windows are stored in those windows. | 1188 the other windows are stored in those windows. |
1084 | 1189 |
1085 @item | 1190 @item |
1086 As long as the selected window displays the current buffer, the window's | 1191 As long as the selected window displays the current buffer, the window's |
1087 point and the buffer's point always move together; they remain equal. | 1192 point and the buffer's point always move together; they remain equal. |
1088 | 1193 @end itemize |
1089 @item | 1194 |
1195 @noindent | |
1090 @xref{Positions}, for more details on buffer positions. | 1196 @xref{Positions}, for more details on buffer positions. |
1091 @end itemize | |
1092 | 1197 |
1093 As far as the user is concerned, point is where the cursor is, and | 1198 As far as the user is concerned, point is where the cursor is, and |
1094 when the user switches to another buffer, the cursor jumps to the | 1199 when the user switches to another buffer, the cursor jumps to the |
1095 position of point in that buffer. | 1200 position of point in that buffer. |
1096 | 1201 |
1108 forms. But that value is hard to find. | 1213 forms. But that value is hard to find. |
1109 @end defun | 1214 @end defun |
1110 | 1215 |
1111 @defun set-window-point window position | 1216 @defun set-window-point window position |
1112 This function positions point in @var{window} at position | 1217 This function positions point in @var{window} at position |
1113 @var{position} in @var{window}'s buffer. | 1218 @var{position} in @var{window}'s buffer. It returns @var{position}. |
1219 | |
1220 If @var{window} is selected, and its buffer is current, | |
1221 this simply does @code{goto-char}. | |
1114 @end defun | 1222 @end defun |
1115 | 1223 |
1116 @node Window Start | 1224 @node Window Start |
1117 @section The Window Start Position | 1225 @section The Window Start Position |
1118 | 1226 |
1146 changes the window-start position; if you move point, do not expect the | 1254 changes the window-start position; if you move point, do not expect the |
1147 window-start position to change in response until after the next | 1255 window-start position to change in response until after the next |
1148 redisplay. | 1256 redisplay. |
1149 | 1257 |
1150 For a realistic example of using @code{window-start}, see the | 1258 For a realistic example of using @code{window-start}, see the |
1151 description of @code{count-lines} in @ref{Text Lines}. | 1259 description of @code{count-lines}. @xref{Definition of count-lines}. |
1152 @end defun | 1260 @end defun |
1153 | 1261 |
1154 @defun window-end &optional window update | 1262 @defun window-end &optional window update |
1155 This function returns the position of the end of the display in window | 1263 This function returns the position of the end of the display in window |
1156 @var{window}. If @var{window} is @code{nil}, the selected window is | 1264 @var{window}. If @var{window} is @code{nil}, the selected window is |
1237 off screen at the next redisplay, then redisplay computes a new window-start | 1345 off screen at the next redisplay, then redisplay computes a new window-start |
1238 position that works well with point, and thus @var{position} is not used. | 1346 position that works well with point, and thus @var{position} is not used. |
1239 @end defun | 1347 @end defun |
1240 | 1348 |
1241 @defun pos-visible-in-window-p &optional position window partially | 1349 @defun pos-visible-in-window-p &optional position window partially |
1242 This function returns @code{t} if @var{position} is within the range of | 1350 This function returns non-@code{nil} if @var{position} is within the |
1243 text currently visible on the screen in @var{window}. It returns | 1351 range of text currently visible on the screen in @var{window}. It |
1244 @code{nil} if @var{position} is scrolled vertically or horizontally out | 1352 returns @code{nil} if @var{position} is scrolled vertically out of |
1245 of view. Locations that are partially obscured are not considered | 1353 view. Locations that are partially obscured are not considered |
1246 visible unless @var{partially} is non-@code{nil}. The argument | 1354 visible unless @var{partially} is non-@code{nil}. The argument |
1247 @var{position} defaults to the current position of point in | 1355 @var{position} defaults to the current position of point in |
1248 @var{window}; @var{window}, to the selected window. | 1356 @var{window}; @var{window}, to the selected window. |
1249 | 1357 |
1358 The @code{pos-visible-in-window-p} function considers only vertical | |
1359 scrolling. If @var{position} is out of view only because @var{window} | |
1360 has been scrolled horizontally, @code{pos-visible-in-window-p} returns | |
1361 non-@code{nil} anyway. @xref{Horizontal Scrolling}. | |
1362 | |
1363 If @var{position} is visible, @code{pos-visible-in-window-p} returns | |
1364 @code{t} if @var{partially} is @code{nil}; if @var{partially} is | |
1365 non-@code{nil}, it returns a list of the form @code{(@var{x} @var{y} | |
1366 @var{partial})}, where @var{x} and @var{y} are the pixel coordinates | |
1367 relative to the top left corner of the window, and @var{partial} is | |
1368 @code{nil} if the character after @var{position} is fully visible; | |
1369 otherwise it is a cons @code{(@var{rtop} . @var{rbot})} where the | |
1370 @var{rtop} and @var{rbot} specify the number of invisible pixels at | |
1371 the top and bottom of the row at @var{position}. | |
1372 | |
1250 Here is an example: | 1373 Here is an example: |
1251 | 1374 |
1252 @example | 1375 @example |
1253 @group | 1376 @group |
1377 ;; @r{If point is off the screen now, recenter it now.} | |
1254 (or (pos-visible-in-window-p | 1378 (or (pos-visible-in-window-p |
1255 (point) (selected-window)) | 1379 (point) (selected-window)) |
1256 (recenter 0)) | 1380 (recenter 0)) |
1257 @end group | 1381 @end group |
1258 @end example | 1382 @end example |
1261 @node Textual Scrolling | 1385 @node Textual Scrolling |
1262 @section Textual Scrolling | 1386 @section Textual Scrolling |
1263 @cindex textual scrolling | 1387 @cindex textual scrolling |
1264 @cindex scrolling textually | 1388 @cindex scrolling textually |
1265 | 1389 |
1266 @dfn{Textual scrolling} means moving the text up or down though a | 1390 @dfn{Textual scrolling} means moving the text up or down through a |
1267 window. It works by changing the value of the window's display-start | 1391 window. It works by changing the value of the window's display-start |
1268 location. It may also change the value of @code{window-point} to keep | 1392 location. It may also change the value of @code{window-point} to keep |
1269 point on the screen. | 1393 point on the screen. |
1270 | 1394 |
1271 Textual scrolling was formerly called ``vertical scrolling,'' but we | 1395 Textual scrolling was formerly called ``vertical scrolling,'' but we |
1292 The textual scrolling functions (aside from | 1416 The textual scrolling functions (aside from |
1293 @code{scroll-other-window}) have unpredictable results if the current | 1417 @code{scroll-other-window}) have unpredictable results if the current |
1294 buffer is different from the buffer that is displayed in the selected | 1418 buffer is different from the buffer that is displayed in the selected |
1295 window. @xref{Current Buffer}. | 1419 window. @xref{Current Buffer}. |
1296 | 1420 |
1421 If the window contains a row which is taller than the height of the | |
1422 window (for example in the presense of a large image), the scroll | |
1423 functions will adjust the window vscroll to scroll the partially | |
1424 visible row. To disable this feature, Lisp code may bind the variable | |
1425 `auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}). | |
1426 | |
1297 @deffn Command scroll-up &optional count | 1427 @deffn Command scroll-up &optional count |
1298 This function scrolls the text in the selected window upward | 1428 This function scrolls the text in the selected window upward |
1299 @var{count} lines. If @var{count} is negative, scrolling is actually | 1429 @var{count} lines. If @var{count} is negative, scrolling is actually |
1300 downward. | 1430 downward. |
1301 | 1431 |
1302 If @var{count} is @code{nil} (or omitted), then the length of scroll | 1432 If @var{count} is @code{nil} (or omitted), then the length of scroll |
1303 is @code{next-screen-context-lines} lines less than the usable height of | 1433 is @code{next-screen-context-lines} lines less than the usable height of |
1304 the window (not counting its mode line). | 1434 the window (not counting its mode line). |
1305 | 1435 |
1306 @code{scroll-up} returns @code{nil}. | 1436 @code{scroll-up} returns @code{nil}, unless it gets an error |
1437 because it can't scroll any further. | |
1307 @end deffn | 1438 @end deffn |
1308 | 1439 |
1309 @deffn Command scroll-down &optional count | 1440 @deffn Command scroll-down &optional count |
1310 This function scrolls the text in the selected window downward | 1441 This function scrolls the text in the selected window downward |
1311 @var{count} lines. If @var{count} is negative, scrolling is actually | 1442 @var{count} lines. If @var{count} is negative, scrolling is actually |
1313 | 1444 |
1314 If @var{count} is omitted or @code{nil}, then the length of the scroll | 1445 If @var{count} is omitted or @code{nil}, then the length of the scroll |
1315 is @code{next-screen-context-lines} lines less than the usable height of | 1446 is @code{next-screen-context-lines} lines less than the usable height of |
1316 the window (not counting its mode line). | 1447 the window (not counting its mode line). |
1317 | 1448 |
1318 @code{scroll-down} returns @code{nil}. | 1449 @code{scroll-down} returns @code{nil}, unless it gets an error because |
1450 it can't scroll any further. | |
1319 @end deffn | 1451 @end deffn |
1320 | 1452 |
1321 @deffn Command scroll-other-window &optional count | 1453 @deffn Command scroll-other-window &optional count |
1322 This function scrolls the text in another window upward @var{count} | 1454 This function scrolls the text in another window upward @var{count} |
1323 lines. Negative values of @var{count}, or @code{nil}, are handled | 1455 lines. Negative values of @var{count}, or @code{nil}, are handled |
1330 | 1462 |
1331 When the selected window is the minibuffer, the next window is normally | 1463 When the selected window is the minibuffer, the next window is normally |
1332 the one at the top left corner. You can specify a different window to | 1464 the one at the top left corner. You can specify a different window to |
1333 scroll, when the minibuffer is selected, by setting the variable | 1465 scroll, when the minibuffer is selected, by setting the variable |
1334 @code{minibuffer-scroll-window}. This variable has no effect when any | 1466 @code{minibuffer-scroll-window}. This variable has no effect when any |
1335 other window is selected. @xref{Minibuffer Misc}. | 1467 other window is selected. When it is non-@code{nil} and the |
1468 minibuffer is selected, it takes precedence over | |
1469 @code{other-window-scroll-buffer}. @xref{Definition of | |
1470 minibuffer-scroll-window}. | |
1336 | 1471 |
1337 When the minibuffer is active, it is the next window if the selected | 1472 When the minibuffer is active, it is the next window if the selected |
1338 window is the one at the bottom right corner. In this case, | 1473 window is the one at the bottom right corner. In this case, |
1339 @code{scroll-other-window} attempts to scroll the minibuffer. If the | 1474 @code{scroll-other-window} attempts to scroll the minibuffer. If the |
1340 minibuffer contains just one line, it has nowhere to scroll to, so the | 1475 minibuffer contains just one line, it has nowhere to scroll to, so the |
1398 only by precisely @var{n} lines, not a smaller number. This feature | 1533 only by precisely @var{n} lines, not a smaller number. This feature |
1399 does not work with @code{scroll-margin}. The default value is zero. | 1534 does not work with @code{scroll-margin}. The default value is zero. |
1400 @end defopt | 1535 @end defopt |
1401 | 1536 |
1402 @defopt scroll-preserve-screen-position | 1537 @defopt scroll-preserve-screen-position |
1403 If this option is non-@code{nil}, the scroll functions move point so | 1538 If this option is @code{t}, scrolling which would move the current |
1404 that the vertical position of the cursor is unchanged, when that is | 1539 point position out of the window chooses the new position of point |
1405 possible. | 1540 so that the vertical position of the cursor is unchanged, if possible. |
1541 | |
1542 If it is non-@code{nil} and not @code{t}, then the scrolling functions | |
1543 always preserve the vertical position of point, if possible. | |
1406 @end defopt | 1544 @end defopt |
1407 | 1545 |
1408 @defopt next-screen-context-lines | 1546 @defopt next-screen-context-lines |
1409 The value of this variable is the number of lines of continuity to | 1547 The value of this variable is the number of lines of continuity to |
1410 retain when scrolling by full screens. For example, @code{scroll-up} | 1548 retain when scrolling by full screens. For example, @code{scroll-up} |
1457 @section Vertical Fractional Scrolling | 1595 @section Vertical Fractional Scrolling |
1458 @cindex Vertical Fractional Scrolling | 1596 @cindex Vertical Fractional Scrolling |
1459 | 1597 |
1460 @dfn{Vertical fractional scrolling} means shifting the image in the | 1598 @dfn{Vertical fractional scrolling} means shifting the image in the |
1461 window up or down by a specified multiple or fraction of a line. | 1599 window up or down by a specified multiple or fraction of a line. |
1462 Starting in Emacs 21, each window has a @dfn{vertical scroll position}, | 1600 Each window has a @dfn{vertical scroll position}, |
1463 which is a number, never less than zero. It specifies how far to raise | 1601 which is a number, never less than zero. It specifies how far to raise |
1464 the contents of the window. Raising the window contents generally makes | 1602 the contents of the window. Raising the window contents generally makes |
1465 all or part of some lines disappear off the top, and all or part of some | 1603 all or part of some lines disappear off the top, and all or part of some |
1466 other lines appear at the bottom. The usual value is zero. | 1604 other lines appear at the bottom. The usual value is zero. |
1467 | 1605 |
1474 What fraction of a line the vertical scrolling covers, or how many | 1612 What fraction of a line the vertical scrolling covers, or how many |
1475 lines, depends on what the lines contain. A value of .5 could scroll a | 1613 lines, depends on what the lines contain. A value of .5 could scroll a |
1476 line whose height is very short off the screen, while a value of 3.3 | 1614 line whose height is very short off the screen, while a value of 3.3 |
1477 could scroll just part of the way through a tall line or an image. | 1615 could scroll just part of the way through a tall line or an image. |
1478 | 1616 |
1479 @defun window-vscroll &optional window | 1617 @defun window-vscroll &optional window pixels-p |
1480 This function returns the current vertical scroll position of | 1618 This function returns the current vertical scroll position of |
1481 @var{window}, If @var{window} is @code{nil}, the selected window is | 1619 @var{window}. If @var{window} is @code{nil}, the selected window is |
1482 used. | 1620 used. If @var{pixels-p} is non-@code{nil}, the return value is |
1621 measured in pixels, rather than in units of the normal line height. | |
1483 | 1622 |
1484 @example | 1623 @example |
1485 @group | 1624 @group |
1486 (window-vscroll) | 1625 (window-vscroll) |
1487 @result{} 0 | 1626 @result{} 0 |
1488 @end group | 1627 @end group |
1489 @end example | 1628 @end example |
1490 @end defun | 1629 @end defun |
1491 | 1630 |
1492 @defun set-window-vscroll window lines | 1631 @defun set-window-vscroll window lines &optional pixels-p |
1493 This function sets @var{window}'s vertical scroll position to | 1632 This function sets @var{window}'s vertical scroll position to |
1494 @var{lines}. The argument @var{lines} should be zero or positive; if | 1633 @var{lines}. The argument @var{lines} should be zero or positive; if |
1495 not, it is taken as zero. | 1634 not, it is taken as zero. |
1496 | 1635 |
1497 If @var{window} is @code{nil}, the selected window is used. | 1636 If @var{window} is @code{nil}, the selected window is used. |
1506 @group | 1645 @group |
1507 (set-window-vscroll (selected-window) 1.2) | 1646 (set-window-vscroll (selected-window) 1.2) |
1508 @result{} 1.13 | 1647 @result{} 1.13 |
1509 @end group | 1648 @end group |
1510 @end example | 1649 @end example |
1511 @end defun | 1650 |
1651 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of | |
1652 pixels. In this case, the return value is @var{lines}. | |
1653 @end defun | |
1654 | |
1655 @defvar auto-window-vscroll | |
1656 If this variable is non-@code{nil}, the line-move, scroll-up, and | |
1657 scroll-down functions will automatically modify the window vscroll to | |
1658 scroll through display rows that are taller that the height of the | |
1659 window, for example in the presense of large images. | |
1660 @end defvar | |
1512 | 1661 |
1513 @node Horizontal Scrolling | 1662 @node Horizontal Scrolling |
1514 @section Horizontal Scrolling | 1663 @section Horizontal Scrolling |
1515 @cindex horizontal scrolling | 1664 @cindex horizontal scrolling |
1516 | 1665 |
1547 reduce the net horizontal scroll to zero. There is no limit to how far | 1696 reduce the net horizontal scroll to zero. There is no limit to how far |
1548 left you can scroll, but eventually all the text will disappear off the | 1697 left you can scroll, but eventually all the text will disappear off the |
1549 left edge. | 1698 left edge. |
1550 | 1699 |
1551 @vindex auto-hscroll-mode | 1700 @vindex auto-hscroll-mode |
1552 In Emacs 21, redisplay automatically alters the horizontal scrolling | 1701 If @code{auto-hscroll-mode} is set, redisplay automatically alters |
1553 of a window as necessary to ensure that point is always visible, if | 1702 the horizontal scrolling of a window as necessary to ensure that point |
1554 @code{auto-hscroll-mode} is set. However, you can still set the | 1703 is always visible. However, you can still set the horizontal |
1555 horizontal scrolling value explicitly. The value you specify serves as | 1704 scrolling value explicitly. The value you specify serves as a lower |
1556 a lower bound for automatic scrolling, i.e. automatic scrolling | 1705 bound for automatic scrolling, i.e. automatic scrolling will not |
1557 will not scroll a window to a column less than the specified one. | 1706 scroll a window to a column less than the specified one. |
1558 | 1707 |
1559 @deffn Command scroll-left &optional count | 1708 @deffn Command scroll-left &optional count set-minimum |
1560 This function scrolls the selected window @var{count} columns to the | 1709 This function scrolls the selected window @var{count} columns to the |
1561 left (or to the right if @var{count} is negative). The default | 1710 left (or to the right if @var{count} is negative). The default |
1562 for @var{count} is the window width, minus 2. | 1711 for @var{count} is the window width, minus 2. |
1563 | 1712 |
1564 The return value is the total amount of leftward horizontal scrolling in | 1713 The return value is the total amount of leftward horizontal scrolling in |
1565 effect after the change---just like the value returned by | 1714 effect after the change---just like the value returned by |
1566 @code{window-hscroll} (below). | 1715 @code{window-hscroll} (below). |
1567 @end deffn | |
1568 | |
1569 @deffn Command scroll-right &optional count | |
1570 This function scrolls the selected window @var{count} columns to the | |
1571 right (or to the left if @var{count} is negative). The default | |
1572 for @var{count} is the window width, minus 2. | |
1573 | |
1574 The return value is the total amount of leftward horizontal scrolling in | |
1575 effect after the change---just like the value returned by | |
1576 @code{window-hscroll} (below). | |
1577 | 1716 |
1578 Once you scroll a window as far right as it can go, back to its normal | 1717 Once you scroll a window as far right as it can go, back to its normal |
1579 position where the total leftward scrolling is zero, attempts to scroll | 1718 position where the total leftward scrolling is zero, attempts to scroll |
1580 any farther right have no effect. | 1719 any farther right have no effect. |
1720 | |
1721 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes | |
1722 the lower bound for automatic scrolling; that is, automatic scrolling | |
1723 will not scroll a window to a column less than the value returned by | |
1724 this function. Interactive calls pass non-@code{nil} for | |
1725 @var{set-minimum}. | |
1726 @end deffn | |
1727 | |
1728 @deffn Command scroll-right &optional count set-minimum | |
1729 This function scrolls the selected window @var{count} columns to the | |
1730 right (or to the left if @var{count} is negative). The default | |
1731 for @var{count} is the window width, minus 2. Aside from the direction | |
1732 of scrolling, this works just like @code{scroll-left}. | |
1581 @end deffn | 1733 @end deffn |
1582 | 1734 |
1583 @defun window-hscroll &optional window | 1735 @defun window-hscroll &optional window |
1584 This function returns the total leftward horizontal scrolling of | 1736 This function returns the total leftward horizontal scrolling of |
1585 @var{window}---the number of columns by which the text in @var{window} | 1737 @var{window}---the number of columns by which the text in @var{window} |
1605 @end group | 1757 @end group |
1606 @end example | 1758 @end example |
1607 @end defun | 1759 @end defun |
1608 | 1760 |
1609 @defun set-window-hscroll window columns | 1761 @defun set-window-hscroll window columns |
1610 This function sets the number of columns from the left margin that | 1762 This function sets horizontal scrolling of @var{window}. The value of |
1611 @var{window} is scrolled from the value of @var{columns}. The argument | 1763 @var{columns} specifies the amount of scrolling, in terms of columns |
1612 @var{columns} should be zero or positive; if not, it is taken as zero. | 1764 from the left margin. The argument @var{columns} should be zero or |
1613 Fractional values of @var{columns} are not supported at present. | 1765 positive; if not, it is taken as zero. Fractional values of |
1766 @var{columns} are not supported at present. | |
1614 | 1767 |
1615 Note that @code{set-window-hscroll} may appear not to work if you test | 1768 Note that @code{set-window-hscroll} may appear not to work if you test |
1616 it by evaluating a call with @kbd{M-:} in a simple way. What happens | 1769 it by evaluating a call with @kbd{M-:} in a simple way. What happens |
1617 is that the function sets the horizontal scroll value and returns, but | 1770 is that the function sets the horizontal scroll value and returns, but |
1618 then redisplay adjusts the horizontal scrolling to make point visible, | 1771 then redisplay adjusts the horizontal scrolling to make point visible, |
1659 The following three functions return size information about a window: | 1812 The following three functions return size information about a window: |
1660 | 1813 |
1661 @defun window-height &optional window | 1814 @defun window-height &optional window |
1662 This function returns the number of lines in @var{window}, including | 1815 This function returns the number of lines in @var{window}, including |
1663 its mode line and header line, if any. If @var{window} fills its | 1816 its mode line and header line, if any. If @var{window} fills its |
1664 entire frame except for the echo area, and there is no tool bar, this | 1817 entire frame except for the echo area, this is typically one less than |
1665 is typically one less than the value of @code{frame-height} on that | 1818 the value of @code{frame-height} on that frame. |
1666 frame. | |
1667 | 1819 |
1668 If @var{window} is @code{nil}, the function uses the selected window. | 1820 If @var{window} is @code{nil}, the function uses the selected window. |
1669 | 1821 |
1670 @example | 1822 @example |
1671 @group | 1823 @group |
1714 @var{bottom})}, all elements relative to 0, 0 at the top left corner of | 1866 @var{bottom})}, all elements relative to 0, 0 at the top left corner of |
1715 the frame. The element @var{right} of the value is one more than the | 1867 the frame. The element @var{right} of the value is one more than the |
1716 rightmost column used by @var{window}, and @var{bottom} is one more than | 1868 rightmost column used by @var{window}, and @var{bottom} is one more than |
1717 the bottommost row used by @var{window} and its mode-line. | 1869 the bottommost row used by @var{window} and its mode-line. |
1718 | 1870 |
1719 If a window has a scroll bar, the right edge value includes the width of | 1871 The edges include the space used by the window's scroll bar, display |
1720 the scroll bar. Otherwise, if the window has a neighbor on the right, | 1872 margins, fringes, header line, and mode line, if it has them. Also, |
1721 its right edge value includes the width of the separator line between | 1873 if the window has a neighbor on the right, its right edge value |
1722 the window and that neighbor. Since the width of the window does not | 1874 includes the width of the separator line between the window and that |
1723 include this separator, the width does not usually equal the difference | 1875 neighbor. Since the width of the window does not include this |
1724 between the right and left edges. | 1876 separator, the width does not usually equal the difference between the |
1725 | 1877 right and left edges. |
1726 Here is the result obtained on a typical 24-line terminal with just one | 1878 @end defun |
1727 window: | 1879 |
1880 @defun window-inside-edges &optional window | |
1881 This is similar to @code{window-edges}, but the edge values | |
1882 it returns include only the text area of the window. They | |
1883 do not include the header line, mode line, scroll bar or | |
1884 vertical separator, fringes, or display margins. | |
1885 @end defun | |
1886 | |
1887 Here are the results obtained on a typical 24-line terminal with just | |
1888 one window, with menu bar enabled: | |
1728 | 1889 |
1729 @example | 1890 @example |
1730 @group | 1891 @group |
1731 (window-edges (selected-window)) | 1892 (window-edges (selected-window)) |
1732 @result{} (0 0 80 23) | 1893 @result{} (0 1 80 23) |
1894 @end group | |
1895 @group | |
1896 (window-inside-edges (selected-window)) | |
1897 @result{} (0 1 80 22) | |
1733 @end group | 1898 @end group |
1734 @end example | 1899 @end example |
1735 | 1900 |
1736 @noindent | 1901 @noindent |
1737 The bottom edge is at line 23 because the last line is the echo area. | 1902 The bottom edge is at line 23 because the last line is the echo area. |
1738 | 1903 The bottom inside edge is at line 22, which is the window's mode line. |
1739 If @var{window} is at the upper left corner of its frame, then | 1904 |
1740 @var{bottom} is the same as the value of @code{(window-height)}, | 1905 If @var{window} is at the upper left corner of its frame, and there is |
1741 @var{right} is almost the same as the value of @code{(window-width)}, | 1906 no menu bar, then @var{bottom} returned by @code{window-edges} is the |
1742 and @var{top} and @var{left} are zero. For example, the edges of the | 1907 same as the value of @code{(window-height)}, @var{right} is almost the |
1743 following window are @w{@samp{0 0 8 5}}. Assuming that the frame has | 1908 same as the value of @code{(window-width)}, and @var{top} and |
1744 more than 8 columns, the last column of the window (column 7) holds a | 1909 @var{left} are zero. For example, the edges of the following window |
1745 border rather than text. The last row (row 4) holds the mode line, | 1910 are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 |
1746 shown here with @samp{xxxxxxxxx}. | 1911 columns, the last column of the window (column 7) holds a border |
1912 rather than text. The last row (row 4) holds the mode line, shown | |
1913 here with @samp{xxxxxxxxx}. | |
1747 | 1914 |
1748 @example | 1915 @example |
1749 @group | 1916 @group |
1750 0 | 1917 0 |
1751 _______ | 1918 _______ |
1759 @end group | 1926 @end group |
1760 @end example | 1927 @end example |
1761 | 1928 |
1762 In the following example, let's suppose that the frame is 7 | 1929 In the following example, let's suppose that the frame is 7 |
1763 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} | 1930 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} |
1764 and the edges of the right window are @w{@samp{4 0 8 3}}. | 1931 and the edges of the right window are @w{@samp{4 0 7 3}}. |
1932 The inside edges of the left window are @w{@samp{0 0 3 2}}, | |
1933 and the inside edges of the right window are @w{@samp{4 0 7 2}}, | |
1765 | 1934 |
1766 @example | 1935 @example |
1767 @group | 1936 @group |
1768 ___ ___ | 1937 ___ ___ |
1769 | | | | 1938 | | | |
1771 xxxxxxxxx | 1940 xxxxxxxxx |
1772 | 1941 |
1773 0 34 7 | 1942 0 34 7 |
1774 @end group | 1943 @end group |
1775 @end example | 1944 @end example |
1945 | |
1946 @defun window-pixel-edges &optional window | |
1947 This function is like @code{window-edges} except that, on a graphical | |
1948 display, the edge values are measured in pixels instead of in | |
1949 character lines and columns. | |
1950 @end defun | |
1951 | |
1952 @defun window-inside-pixel-edges &optional window | |
1953 This function is like @code{window-inside-edges} except that, on a | |
1954 graphical display, the edge values are measured in pixels instead of | |
1955 in character lines and columns. | |
1776 @end defun | 1956 @end defun |
1777 | 1957 |
1778 @node Resizing Windows | 1958 @node Resizing Windows |
1779 @section Changing the Size of a Window | 1959 @section Changing the Size of a Window |
1780 @cindex window resizing | 1960 @cindex window resizing |
1822 It could be defined as follows: | 2002 It could be defined as follows: |
1823 | 2003 |
1824 @example | 2004 @example |
1825 @group | 2005 @group |
1826 (defun enlarge-window-horizontally (columns) | 2006 (defun enlarge-window-horizontally (columns) |
2007 (interactive "p") | |
1827 (enlarge-window columns t)) | 2008 (enlarge-window columns t)) |
1828 @end group | 2009 @end group |
1829 @end example | 2010 @end example |
1830 @end deffn | 2011 @end deffn |
1831 | 2012 |
1844 It could be defined as follows: | 2025 It could be defined as follows: |
1845 | 2026 |
1846 @example | 2027 @example |
1847 @group | 2028 @group |
1848 (defun shrink-window-horizontally (columns) | 2029 (defun shrink-window-horizontally (columns) |
2030 (interactive "p") | |
1849 (shrink-window columns t)) | 2031 (shrink-window columns t)) |
1850 @end group | 2032 @end group |
1851 @end example | 2033 @end example |
1852 @end deffn | 2034 @end deffn |
1853 | 2035 |
2036 @defun adjust-window-trailing-edge window delta horizontal | |
2037 This function makes the selected window @var{delta} lines taller or | |
2038 @var{delta} columns wider, by moving the bottom or right edge. This | |
2039 function does not delete other windows; if it cannot make the | |
2040 requested size adjustment, it signals an error. On success, this | |
2041 function returns @code{nil}. | |
2042 @end defun | |
2043 | |
2044 @defun fit-window-to-buffer &optional window max-height min-height | |
2045 This function makes @var{window} the right height to display its | |
2046 contents exactly. If @var{window} is omitted or @code{nil}, it uses | |
2047 the selected window. | |
2048 | |
2049 The argument @var{max-height} specifies the maximum height the window | |
2050 is allowed to be; @code{nil} means use the frame height. The argument | |
2051 @var{min-height} specifies the minimum height for the window; | |
2052 @code{nil} means use @code{window-min-height}. All these height | |
2053 values include the mode-line and/or header-line. | |
2054 @end defun | |
2055 | |
1854 @deffn Command shrink-window-if-larger-than-buffer &optional window | 2056 @deffn Command shrink-window-if-larger-than-buffer &optional window |
1855 This command shrinks @var{window} to be as small as possible while still | 2057 This command shrinks @var{window} vertically to be as small as |
1856 showing the full contents of its buffer---but not less than | 2058 possible while still showing the full contents of its buffer---but not |
1857 @code{window-min-height} lines. If @var{window} is not given, | 2059 less than @code{window-min-height} lines. If @var{window} is not |
1858 it defaults to the selected window. | 2060 given, it defaults to the selected window. |
1859 | 2061 |
1860 However, the command does nothing if the window is already too small to | 2062 However, the command does nothing if the window is already too small to |
1861 display the whole text of the buffer, or if part of the contents are | 2063 display the whole text of the buffer, or if part of the contents are |
1862 currently scrolled off screen, or if the window is not the full width of | 2064 currently scrolled off screen, or if the window is not the full width of |
1863 its frame, or if the window is the only window in its frame. | 2065 its frame, or if the window is the only window in its frame. |
2066 | |
2067 This command returns non-@code{nil} if it actually shrank the window | |
2068 and @code{nil} otherwise. | |
1864 @end deffn | 2069 @end deffn |
1865 | 2070 |
1866 @tindex window-size-fixed | 2071 @tindex window-size-fixed |
1867 @defvar window-size-fixed | 2072 @defvar window-size-fixed |
1868 If this variable is non-@code{nil}, in any given buffer, | 2073 If this variable is non-@code{nil}, in any given buffer, |
1869 then the size of any window displaying the buffer remains fixed | 2074 then the size of any window displaying the buffer remains fixed |
1870 unless you explicitly change it or Emacs has no other choice. | 2075 unless you explicitly change it or Emacs has no other choice. |
1871 (This feature is new in Emacs 21.) | |
1872 | 2076 |
1873 If the value is @code{height}, then only the window's height is fixed; | 2077 If the value is @code{height}, then only the window's height is fixed; |
1874 if the value is @code{width}, then only the window's width is fixed. | 2078 if the value is @code{width}, then only the window's width is fixed. |
1875 Any other non-@code{nil} value fixes both the width and the height. | 2079 Any other non-@code{nil} value fixes both the width and the height. |
1876 | 2080 |
1877 The usual way to use this variable is to give it a buffer-local value in | 2081 This variable automatically becomes buffer-local when set. |
1878 a particular buffer. That way, the windows (but usually there is only | |
1879 one) displaying that buffer have fixed size. | |
1880 | 2082 |
1881 Explicit size-change functions such as @code{enlarge-window} | 2083 Explicit size-change functions such as @code{enlarge-window} |
1882 get an error if they would have to change a window size which is fixed. | 2084 get an error if they would have to change a window size which is fixed. |
1883 Therefore, when you want to change the size of such a window, | 2085 Therefore, when you want to change the size of such a window, |
1884 you should bind @code{window-size-fixed} to @code{nil}, like this: | 2086 you should bind @code{window-size-fixed} to @code{nil}, like this: |
1959 The coordinates are in the vertical line between @var{window} and its | 2161 The coordinates are in the vertical line between @var{window} and its |
1960 neighbor to the right. This value occurs only if the window doesn't | 2162 neighbor to the right. This value occurs only if the window doesn't |
1961 have a scroll bar; positions in a scroll bar are considered outside the | 2163 have a scroll bar; positions in a scroll bar are considered outside the |
1962 window for these purposes. | 2164 window for these purposes. |
1963 | 2165 |
2166 @item left-fringe | |
2167 @itemx right-fringe | |
2168 The coordinates are in the left or right fringe of the window. | |
2169 | |
2170 @item left-margin | |
2171 @itemx right-margin | |
2172 The coordinates are in the left or right margin of the window. | |
2173 | |
1964 @item nil | 2174 @item nil |
1965 The coordinates are not in any part of @var{window}. | 2175 The coordinates are not in any part of @var{window}. |
1966 @end table | 2176 @end table |
1967 | 2177 |
1968 The function @code{coordinates-in-window-p} does not require a frame as | 2178 The function @code{coordinates-in-window-p} does not require a frame as |
1969 argument because it always uses the frame that @var{window} is on. | 2179 argument because it always uses the frame that @var{window} is on. |
2180 @end defun | |
2181 | |
2182 @node Window Tree | |
2183 @section The Window Tree | |
2184 @cindex window tree | |
2185 | |
2186 A @dfn{window tree} specifies the layout, size, and relationship | |
2187 between all windows in one frame. | |
2188 | |
2189 @defun window-tree &optional frame | |
2190 This function returns the window tree for frame @var{frame}. | |
2191 If @var{frame} is omitted, the selected frame is used. | |
2192 | |
2193 The return value is a list of the form @code{(@var{root} @var{mini})}, | |
2194 where @var{root} represents the window tree of the frame's | |
2195 root window, and @var{mini} is the frame's minibuffer window. | |
2196 | |
2197 If the root window is not split, @var{root} is the root window itself. | |
2198 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} | |
2199 @var{w2} ...)} where @var{dir} is @code{nil} for a horisontal split, | |
2200 and @code{t} for a vertical split, @var{edges} gives the combined size and | |
2201 position of the subwindows in the split, and the rest of the elements | |
2202 are the subwindows in the split. Each of the subwindows may again be | |
2203 a window or a list representing a window split, and so on. The | |
2204 @var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} | |
2205 similar to the value returned by @code{window-edges}. | |
1970 @end defun | 2206 @end defun |
1971 | 2207 |
1972 @node Window Configurations | 2208 @node Window Configurations |
1973 @section Window Configurations | 2209 @section Window Configurations |
1974 @cindex window configurations | 2210 @cindex window configurations |
1975 @cindex saving window information | 2211 @cindex saving window information |
1976 | 2212 |
1977 A @dfn{window configuration} records the entire layout of one | 2213 A @dfn{window configuration} records the entire layout of one |
1978 frame---all windows, their sizes, which buffers they contain, what | 2214 frame---all windows, their sizes, which buffers they contain, what |
1979 part of each buffer is displayed, and the values of point and the | 2215 part of each buffer is displayed, and the values of point and the |
1980 mark. It also includes the values of @code{window-min-height}, | 2216 mark; also their fringes, margins, and scroll bar settings. It also |
2217 includes the values of @code{window-min-height}, | |
1981 @code{window-min-width} and @code{minibuffer-scroll-window}. An | 2218 @code{window-min-width} and @code{minibuffer-scroll-window}. An |
1982 exception is made for point in the selected window for the current | 2219 exception is made for point in the selected window for the current |
1983 buffer; its value is not saved in the window configuration. | 2220 buffer; its value is not saved in the window configuration. |
1984 | 2221 |
1985 You can bring back an entire previous layout by restoring a window | 2222 You can bring back an entire previous layout by restoring a window |
2007 know how to tell whether the new configuration actually differs from the | 2244 know how to tell whether the new configuration actually differs from the |
2008 old one. | 2245 old one. |
2009 | 2246 |
2010 If the frame which @var{configuration} was saved from is dead, all this | 2247 If the frame which @var{configuration} was saved from is dead, all this |
2011 function does is restore the three variables @code{window-min-height}, | 2248 function does is restore the three variables @code{window-min-height}, |
2012 @code{window-min-width} and @code{minibuffer-scroll-window}. | 2249 @code{window-min-width} and @code{minibuffer-scroll-window}. In this |
2250 case, the function returns @code{nil}. Otherwise, it returns @code{t}. | |
2013 | 2251 |
2014 Here is a way of using this function to get the same effect | 2252 Here is a way of using this function to get the same effect |
2015 as @code{save-window-excursion}: | 2253 as @code{save-window-excursion}: |
2016 | 2254 |
2017 @example | 2255 @example |
2026 @end defun | 2264 @end defun |
2027 | 2265 |
2028 @defspec save-window-excursion forms@dots{} | 2266 @defspec save-window-excursion forms@dots{} |
2029 This special form records the window configuration, executes @var{forms} | 2267 This special form records the window configuration, executes @var{forms} |
2030 in sequence, then restores the earlier window configuration. The window | 2268 in sequence, then restores the earlier window configuration. The window |
2031 configuration includes the value of point and the portion of the buffer | 2269 configuration includes, for each window, the value of point and the |
2032 that is visible. It also includes the choice of selected window. | 2270 portion of the buffer that is visible. It also includes the choice of |
2033 However, it does not include the value of point in the current buffer; | 2271 selected window. However, it does not include the value of point in |
2034 use @code{save-excursion} also, if you wish to preserve that. | 2272 the current buffer; use @code{save-excursion} also, if you wish to |
2035 | 2273 preserve that. |
2036 Don't use this construct when @code{save-selected-window} is all you need. | 2274 |
2275 Don't use this construct when @code{save-selected-window} is sufficient. | |
2037 | 2276 |
2038 Exit from @code{save-window-excursion} always triggers execution of the | 2277 Exit from @code{save-window-excursion} always triggers execution of the |
2039 @code{window-size-change-functions}. (It doesn't know how to tell | 2278 @code{window-size-change-functions}. (It doesn't know how to tell |
2040 whether the restored configuration actually differs from the one in | 2279 whether the restored configuration actually differs from the one in |
2041 effect at the end of the @var{forms}.) | 2280 effect at the end of the @var{forms}.) |
2076 The function @code{equal} can also compare two window configurations; it | 2315 The function @code{equal} can also compare two window configurations; it |
2077 regards configurations as unequal if they differ in any respect, even a | 2316 regards configurations as unequal if they differ in any respect, even a |
2078 saved point or mark. | 2317 saved point or mark. |
2079 @end defun | 2318 @end defun |
2080 | 2319 |
2081 Primitives to look inside of window configurations would make sense, | 2320 @defun window-configuration-frame config |
2082 but none are implemented. It is not clear they are useful enough to | 2321 This function returns the frame for which the window configuration |
2083 be worth implementing. See the file @file{winner.el} for some more | 2322 @var{config} was made. |
2084 operations on windows configurations. | 2323 @end defun |
2324 | |
2325 Other primitives to look inside of window configurations would make | |
2326 sense, but are not implemented because we did not need them. See the | |
2327 file @file{winner.el} for some more operations on windows | |
2328 configurations. | |
2085 | 2329 |
2086 @node Window Hooks | 2330 @node Window Hooks |
2087 @section Hooks for Window Scrolling and Changes | 2331 @section Hooks for Window Scrolling and Changes |
2088 | 2332 |
2089 This section describes how a Lisp program can take action whenever a | 2333 This section describes how a Lisp program can take action whenever a |
2090 window displays a different part of its buffer or a different buffer. | 2334 window displays a different part of its buffer or a different buffer. |
2091 There are three actions that can change this: scrolling the window, | 2335 There are three actions that can change this: scrolling the window, |
2092 switching buffers in the window, and changing the size of the window. | 2336 switching buffers in the window, and changing the size of the window. |
2093 The first two actions run @code{window-scroll-functions}; the last runs | 2337 The first two actions run @code{window-scroll-functions}; the last runs |
2094 @code{window-size-change-functions}. The paradigmatic use of these | 2338 @code{window-size-change-functions}. |
2095 hooks is in the implementation of Lazy Lock mode; see @ref{Support | |
2096 Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}. | |
2097 | 2339 |
2098 @defvar window-scroll-functions | 2340 @defvar window-scroll-functions |
2099 This variable holds a list of functions that Emacs should call before | 2341 This variable holds a list of functions that Emacs should call before |
2100 redisplaying a window with scrolling. It is not a normal hook, because | 2342 redisplaying a window with scrolling. It is not a normal hook, because |
2101 each function is called with two arguments: the window, and its new | 2343 each function is called with two arguments: the window, and its new |
2146 @var{position}. | 2388 @var{position}. |
2147 @end defun | 2389 @end defun |
2148 | 2390 |
2149 @defun window-redisplay-end-trigger &optional window | 2391 @defun window-redisplay-end-trigger &optional window |
2150 This function returns @var{window}'s current end trigger position. | 2392 This function returns @var{window}'s current end trigger position. |
2393 If @var{window} is @code{nil} or omitted, it uses the selected window. | |
2151 @end defun | 2394 @end defun |
2152 | 2395 |
2153 @defvar window-configuration-change-hook | 2396 @defvar window-configuration-change-hook |
2154 A normal hook that is run every time you change the window configuration | 2397 A normal hook that is run every time you change the window configuration |
2155 of an existing frame. This includes splitting or deleting windows, | 2398 of an existing frame. This includes splitting or deleting windows, |
2156 changing the sizes of windows, or displaying a different buffer in a | 2399 changing the sizes of windows, or displaying a different buffer in a |
2157 window. The frame whose window configuration has changed is the | 2400 window. The frame whose window configuration has changed is the |
2158 selected frame when this hook runs. | 2401 selected frame when this hook runs. |
2159 @end defvar | 2402 @end defvar |
2403 | |
2404 @ignore | |
2405 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 | |
2406 @end ignore |