2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/windows.info
6 @node Windows, Frames, Buffers, Top
9 This chapter describes most of the functions and variables related to
10 Emacs windows. See @ref{Display}, for information on how text is
14 * Basic Windows:: Basic information on using windows.
15 * Splitting Windows:: Splitting one window into two windows.
16 * Deleting Windows:: Deleting a window gives its space to other windows.
17 * Selecting Windows:: The selected window is the one that you edit in.
18 * Cyclic Window Ordering:: Moving around the existing windows.
19 * Buffers and Windows:: Each window displays the contents of a buffer.
20 * Displaying Buffers:: Higher-lever functions for displaying a buffer
21 and choosing a window for it.
22 * Choosing Window:: How to choose a window for displaying a buffer.
23 * Window Point:: Each window has its own location of point.
24 * Window Start:: The display-start position controls which text
25 is on-screen in the window.
26 * Vertical Scrolling:: Moving text up and down in the window.
27 * Horizontal Scrolling:: Moving text sideways on the window.
28 * Size of Window:: Accessing the size of a window.
29 * Position of Window:: Accessing the position of a window.
30 * Resizing Windows:: Changing the size of a window.
31 * Window Configurations:: Saving and restoring the state of the screen.
35 @section Basic Concepts of Emacs Windows
37 @cindex selected window
39 A @dfn{window} in XEmacs is the physical area of the screen in which a
40 buffer is displayed. The term is also used to refer to a Lisp object that
41 represents that screen area in XEmacs Lisp. It should be
42 clear from the context which is meant.
44 XEmacs groups windows into frames. A frame represents an area of
45 screen available for XEmacs to use. Each frame always contains at least
46 one window, but you can subdivide it vertically or horizontally into
47 multiple nonoverlapping Emacs windows.
49 In each frame, at any time, one and only one window is designated as
50 @dfn{selected within the frame}. The frame's cursor appears in that
51 window. At ant time, one frame is the selected frame; and the window
52 selected within that frame is @dfn{the selected window}. The selected
53 window's buffer is usually the current buffer (except when
54 @code{set-buffer} has been used). @xref{Current Buffer}.
56 For practical purposes, a window exists only while it is displayed in
57 a frame. Once removed from the frame, the window is effectively deleted
58 and should not be used, @emph{even though there may still be references
59 to it} from other Lisp objects. Restoring a saved window configuration
60 is the only way for a window no longer on the screen to come back to
61 life. (@xref{Deleting Windows}.)
63 Each window has the following attributes:
76 window edges with respect to the frame or screen
79 the buffer it displays
82 position within the buffer at the upper left of the window
85 amount of horizontal scrolling, in columns
94 how recently the window was selected
97 @cindex multiple windows
98 Users create multiple windows so they can look at several buffers at
99 once. Lisp libraries use multiple windows for a variety of reasons, but
100 most often to display related information. In Rmail, for example, you
101 can move through a summary buffer in one window while the other window
102 shows messages one at a time as they are reached.
104 The meaning of ``window'' in XEmacs is similar to what it means in the
105 context of general-purpose window systems such as X, but not identical.
106 The X Window System places X windows on the screen; XEmacs uses one or
107 more X windows as frames, and subdivides them into
108 Emacs windows. When you use XEmacs on a character-only terminal, XEmacs
109 treats the whole terminal screen as one frame.
111 @cindex terminal frame
112 @cindex frame of terminal
113 @cindex tiled windows
114 Most window systems support arbitrarily located overlapping windows.
115 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
116 together they fill the whole screen or frame. Because of the way
117 in which XEmacs creates new windows and resizes them, you can't create
118 every conceivable tiling of windows on an Emacs frame. @xref{Splitting
119 Windows}, and @ref{Size of Window}.
121 @xref{Display}, for information on how the contents of the
122 window's buffer are displayed in the window.
124 @defun windowp object
125 This function returns @code{t} if @var{object} is a window.
128 @node Splitting Windows
129 @section Splitting Windows
130 @cindex splitting windows
131 @cindex window splitting
133 The functions described here are the primitives used to split a window
134 into two windows. Two higher level functions sometimes split a window,
135 but not always: @code{pop-to-buffer} and @code{display-buffer}
136 (@pxref{Displaying Buffers}).
138 The functions described here do not accept a buffer as an argument.
139 The two ``halves'' of the split window initially display the same buffer
140 previously visible in the window that was split.
142 @defun one-window-p &optional no-mini all-frames
143 This function returns non-@code{nil} if there is only one window. The
144 argument @var{no-mini}, if non-@code{nil}, means don't count the
145 minibuffer even if it is active; otherwise, the minibuffer window is
146 included, if active, in the total number of windows which is compared
149 The argument @var{all-frame} controls which set of windows are
153 If it is @code{nil} or omitted, then count only the selected frame, plus
154 the minibuffer it uses (which may be on another frame).
156 If it is @code{t}, then windows on all frames that currently exist
157 (including invisible and iconified frames) are counted.
159 If it is the symbol @code{visible}, then windows on all visible frames
162 If it is the number 0, then windows on all visible and iconified frames
165 If it is any other value, then precisely the windows in @var{window}'s
166 frame are counted, excluding the minibuffer in use if it lies in
171 @deffn Command split-window &optional window size horizontal
172 This function splits @var{window} into two windows. The original
173 window @var{window} remains the selected window, but occupies only
174 part of its former screen area. The rest is occupied by a newly created
175 window which is returned as the value of this function.
177 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
178 two side by side windows. The original window @var{window} keeps the
179 leftmost @var{size} columns, and gives the rest of the columns to the
180 new window. Otherwise, it splits into windows one above the other, and
181 @var{window} keeps the upper @var{size} lines and gives the rest of the
182 lines to the new window. The original window is therefore the
183 left-hand or upper of the two, and the new window is the right-hand or
186 If @var{window} is omitted or @code{nil}, then the selected window is
187 split. If @var{size} is omitted or @code{nil}, then @var{window} is
188 divided evenly into two parts. (If there is an odd line, it is
189 allocated to the new window.) When @code{split-window} is called
190 interactively, all its arguments are @code{nil}.
192 The following example starts with one window on a frame that is 50
193 lines high by 80 columns wide; then the window is split.
197 (setq w (selected-window))
198 @result{} #<window 8 on windows.texi>
199 (window-edges) ; @r{Edges in order:}
200 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
204 ;; @r{Returns window created}
205 (setq w2 (split-window w 15))
206 @result{} #<window 28 on windows.texi>
210 @result{} (0 15 80 50) ; @r{Bottom window;}
215 @result{} (0 0 80 15) ; @r{Top window}
219 The frame looks like this:
235 Next, the top window is split horizontally:
239 (setq w3 (split-window w 35 t))
240 @result{} #<window 32 on windows.texi>
244 @result{} (35 0 80 15) ; @r{Left edge at column 35}
248 @result{} (0 0 35 15) ; @r{Right edge at column 35}
252 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
257 Now, the screen looks like this:
274 Normally, Emacs indicates the border between two side-by-side windows
275 with a scroll bar (@pxref{X Frame Properties,Scroll Bars}) or @samp{|}
276 characters. The display table can specify alternative border
277 characters; see @ref{Display Tables}.
280 @deffn Command split-window-vertically &optional size
281 This function splits the selected window into two windows, one above
282 the other, leaving the selected window with @var{size} lines.
284 This function is simply an interface to @code{split-windows}.
285 Here is the complete function definition for it:
289 (defun split-window-vertically (&optional arg)
290 "Split current window into two windows, one above the other."
292 (split-window nil (and arg (prefix-numeric-value arg))))
297 @deffn Command split-window-horizontally &optional size
298 This function splits the selected window into two windows
299 side-by-side, leaving the selected window with @var{size} columns.
301 This function is simply an interface to @code{split-windows}. Here is
302 the complete definition for @code{split-window-horizontally} (except for
303 part of the documentation string):
307 (defun split-window-horizontally (&optional arg)
308 "Split selected window into two windows, side by side..."
310 (split-window nil (and arg (prefix-numeric-value arg)) t))
315 @defun one-window-p &optional no-mini all-frames
316 This function returns non-@code{nil} if there is only one window. The
317 argument @var{no-mini}, if non-@code{nil}, means don't count the
318 minibuffer even if it is active; otherwise, the minibuffer window is
319 included, if active, in the total number of windows, which is compared
322 The argument @var{all-frames} specifies which frames to consider. Here
323 are the possible values and their meanings:
327 Count the windows in the selected frame, plus the minibuffer used
328 by that frame even if it lies in some other frame.
331 Count all windows in all existing frames.
334 Count all windows in all visible frames.
337 Count all windows in all visible or iconified frames.
340 Count precisely the windows in the selected frame, and no others.
344 @node Deleting Windows
345 @section Deleting Windows
346 @cindex deleting windows
348 A window remains visible on its frame unless you @dfn{delete} it by
349 calling certain functions that delete windows. A deleted window cannot
350 appear on the screen, but continues to exist as a Lisp object until
351 there are no references to it. There is no way to cancel the deletion
352 of a window aside from restoring a saved window configuration
353 (@pxref{Window Configurations}). Restoring a window configuration also
354 deletes any windows that aren't part of that configuration.
356 When you delete a window, the space it took up is given to one
357 adjacent sibling. (In Emacs version 18, the space was divided evenly
358 among all the siblings.)
361 @defun window-live-p window
362 This function returns @code{nil} if @var{window} is deleted, and
365 @strong{Warning:} Erroneous information or fatal errors may result from
366 using a deleted window as if it were live.
369 @deffn Command delete-window &optional window
370 This function removes @var{window} from the display. If @var{window}
371 is omitted, then the selected window is deleted. An error is signaled
372 if there is only one window when @code{delete-window} is called.
374 This function returns @code{nil}.
376 When @code{delete-window} is called interactively, @var{window}
377 defaults to the selected window.
380 @deffn Command delete-other-windows &optional window
381 This function makes @var{window} the only window on its frame, by
382 deleting the other windows in that frame. If @var{window} is omitted or
383 @code{nil}, then the selected window is used by default.
385 The result is @code{nil}.
388 @deffn Command delete-windows-on buffer &optional frame
389 This function deletes all windows showing @var{buffer}. If there are
390 no windows showing @var{buffer}, it does nothing.
392 @code{delete-windows-on} operates frame by frame. If a frame has
393 several windows showing different buffers, then those showing
394 @var{buffer} are removed, and the others expand to fill the space. If
395 all windows in some frame are showing @var{buffer} (including the case
396 where there is only one window), then the frame reverts to having a
397 single window showing another buffer chosen with @code{other-buffer}.
398 @xref{The Buffer List}.
400 The argument @var{frame} controls which frames to operate on:
404 If it is @code{nil}, operate on the selected frame.
406 If it is @code{t}, operate on all frames.
408 If it is @code{visible}, operate on all visible frames.
410 If it is 0, operate on all visible or iconified frames.
412 If it is a frame, operate on that frame.
415 This function always returns @code{nil}.
418 @node Selecting Windows
419 @section Selecting Windows
420 @cindex selecting windows
422 When a window is selected, the buffer in the window becomes the current
423 buffer, and the cursor will appear in it.
425 @defun selected-window &optional device
426 This function returns the selected window. This is the window in
427 which the cursor appears and to which many commands apply. Each
428 separate device can have its own selected window, which is remembered
429 as focus changes from device to device. Optional argument @var{device}
430 specifies which device to return the selected window for, and defaults
431 to the selected device.
434 @defun select-window window &optional norecord
435 This function makes @var{window} the selected window. The cursor then
436 appears in @var{window} (on redisplay). The buffer being displayed in
437 @var{window} is immediately designated the current buffer.
439 If optional argument @var{norecord} is non-@code{nil} then the global
440 and per-frame buffer orderings are not modified, as by the function
441 @code{record-buffer}.
443 The return value is @var{window}.
447 (setq w (next-window))
449 @result{} #<window 65 on windows.texi>
454 @defmac save-selected-window forms@dots{}
455 This macro records the selected window, executes @var{forms}
456 in sequence, then restores the earlier selected window.
457 It does not save or restore anything about the sizes, arrangement
458 or contents of windows; therefore, if the @var{forms} change them,
459 the changes are permanent.
462 @cindex finding windows
463 The following functions choose one of the windows on the screen,
464 offering various criteria for the choice.
466 @defun get-lru-window &optional frame
467 This function returns the window least recently ``used'' (that is,
468 selected). The selected window is always the most recently used window.
470 The selected window can be the least recently used window if it is the
471 only window. A newly created window becomes the least recently used
472 window until it is selected. A minibuffer window is never a candidate.
474 The argument @var{frame} controls which windows are considered.
478 If it is @code{nil}, consider windows on the selected frame.
480 If it is @code{t}, consider windows on all frames.
482 If it is @code{visible}, consider windows on all visible frames.
484 If it is 0, consider windows on all visible or iconified frames.
486 If it is a frame, consider windows on that frame.
490 @defun get-largest-window &optional frame
491 This function returns the window with the largest area (height times
492 width). If there are no side-by-side windows, then this is the window
493 with the most lines. A minibuffer window is never a candidate.
495 If there are two windows of the same size, then the function returns
496 the window that is first in the cyclic ordering of windows (see
497 following section), starting from the selected window.
499 The argument @var{frame} controls which set of windows are
500 considered. See @code{get-lru-window}, above.
503 @node Cyclic Window Ordering
504 @section Cyclic Ordering of Windows
505 @cindex cyclic ordering of windows
506 @cindex ordering of windows, cyclic
507 @cindex window ordering, cyclic
509 When you use the command @kbd{C-x o} (@code{other-window}) to select
510 the next window, it moves through all the windows on the screen in a
511 specific cyclic order. For any given configuration of windows, this
512 order never varies. It is called the @dfn{cyclic ordering of windows}.
514 This ordering generally goes from top to bottom, and from left to
515 right. But it may go down first or go right first, depending on the
516 order in which the windows were split.
518 If the first split was vertical (into windows one above each other),
519 and then the subwindows were split horizontally, then the ordering is
520 left to right in the top of the frame, and then left to right in the
521 next lower part of the frame, and so on. If the first split was
522 horizontal, the ordering is top to bottom in the left part, and so on.
523 In general, within each set of siblings at any level in the window tree,
524 the order is left to right, or top to bottom.
526 @defun next-window &optional window minibuf all-frames
527 @cindex minibuffer window
528 This function returns the window following @var{window} in the cyclic
529 ordering of windows. This is the window that @kbd{C-x o} would select
530 if typed when @var{window} is selected. If @var{window} is the only
531 window visible, then this function returns @var{window}. If omitted,
532 @var{window} defaults to the selected window.
534 The value of the argument @var{minibuf} determines whether the
535 minibuffer is included in the window order. Normally, when
536 @var{minibuf} is @code{nil}, the minibuffer is included if it is
537 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
538 window is active while the minibuffer is in use. @xref{Minibuffers}.)
540 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
541 minibuffer window even if it is not active.
543 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
544 window is not included even if it is active.
546 The argument @var{all-frames} specifies which frames to consider. Here
547 are the possible values and their meanings:
551 Consider all the windows in @var{window}'s frame, plus the minibuffer
552 used by that frame even if it lies in some other frame.
555 Consider all windows in all existing frames.
558 Consider all windows in all visible frames. (To get useful results, you
559 must ensure @var{window} is in a visible frame.)
562 Consider all windows in all visible or iconified frames.
565 Consider precisely the windows in @var{window}'s frame, and no others.
568 This example assumes there are two windows, both displaying the
569 buffer @samp{windows.texi}:
574 @result{} #<window 56 on windows.texi>
577 (next-window (selected-window))
578 @result{} #<window 52 on windows.texi>
581 (next-window (next-window (selected-window)))
582 @result{} #<window 56 on windows.texi>
587 @defun previous-window &optional window minibuf all-frames
588 This function returns the window preceding @var{window} in the cyclic
589 ordering of windows. The other arguments specify which windows to
590 include in the cycle, as in @code{next-window}.
593 @deffn Command other-window count &optional frame
594 This function selects the @var{count}th following window in the cyclic
595 order. If count is negative, then it selects the @minus{}@var{count}th
596 preceding window. It returns @code{nil}.
598 In an interactive call, @var{count} is the numeric prefix argument.
600 The argument @var{frame} controls which set of windows are considered.
603 If it is @code{nil} or omitted, then windows on the selected frame are
606 If it is a frame, then windows on that frame are considered.
608 If it is @code{t}, then windows on all frames that currently exist
609 (including invisible and iconified frames) are considered.
611 If it is the symbol @code{visible}, then windows on all visible frames
614 If it is the number 0, then windows on all visible and iconified frames
617 If it is any other value, then the behavior is undefined.
622 @defun walk-windows proc &optional minibuf all-frames
623 This function cycles through all windows, calling @code{proc}
624 once for each window with the window as its sole argument.
626 The optional arguments @var{minibuf} and @var{all-frames} specify the
627 set of windows to include in the scan. See @code{next-window}, above,
631 @node Buffers and Windows
632 @section Buffers and Windows
633 @cindex examining windows
634 @cindex windows, controlling precisely
635 @cindex buffers, controlled in windows
637 This section describes low-level functions to examine windows or to
638 display buffers in windows in a precisely controlled fashion.
640 See the following section for
643 @xref{Displaying Buffers}, for
645 related functions that find a window to use and specify a buffer for it.
646 The functions described there are easier to use than these, but they
647 employ heuristics in choosing or creating a window; use these functions
648 when you need complete control.
650 @defun set-window-buffer window buffer-or-name
651 This function makes @var{window} display @var{buffer-or-name} as its
652 contents. It returns @code{nil}.
656 (set-window-buffer (selected-window) "foo")
662 @defun window-buffer &optional window
663 This function returns the buffer that @var{window} is displaying. If
664 @var{window} is omitted, this function returns the buffer for the
670 @result{} #<buffer windows.texi>
675 @defun get-buffer-window buffer-or-name &optional frame
676 This function returns a window currently displaying
677 @var{buffer-or-name}, or @code{nil} if there is none. If there are
678 several such windows, then the function returns the first one in the
679 cyclic ordering of windows, starting from the selected window.
680 @xref{Cyclic Window Ordering}.
682 The argument @var{all-frames} controls which windows to consider.
686 If it is @code{nil}, consider windows on the selected frame.
688 If it is @code{t}, consider windows on all frames.
690 If it is @code{visible}, consider windows on all visible frames.
692 If it is 0, consider windows on all visible or iconified frames.
694 If it is a frame, consider windows on that frame.
698 @node Displaying Buffers
699 @section Displaying Buffers in Windows
700 @cindex switching to a buffer
701 @cindex displaying a buffer
703 In this section we describe convenient functions that choose a window
704 automatically and use it to display a specified buffer. These functions
705 can also split an existing window in certain circumstances. We also
706 describe variables that parameterize the heuristics used for choosing a
709 See the preceding section for
712 @xref{Buffers and Windows}, for
714 low-level functions that give you more precise control.
716 Do not use the functions in this section in order to make a buffer
717 current so that a Lisp program can access or modify it; they are too
718 drastic for that purpose, since they change the display of buffers in
719 windows, which is gratuitous and will surprise the user. Instead, use
720 @code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
721 (@pxref{Excursions}), which designate buffers as current for programmed
722 access without affecting the display of buffers in windows.
724 @deffn Command switch-to-buffer buffer-or-name &optional norecord
725 This function makes @var{buffer-or-name} the current buffer, and also
726 displays the buffer in the selected window. This means that a human can
727 see the buffer and subsequent keyboard commands will apply to it.
728 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
729 the current buffer but does not display it in the selected window.
730 @xref{Current Buffer}.
732 If @var{buffer-or-name} does not identify an existing buffer, then a new
733 buffer by that name is created. The major mode for the new buffer is
734 set according to the variable @code{default-major-mode}. @xref{Auto
737 Normally the specified buffer is put at the front of the buffer list.
738 This affects the operation of @code{other-buffer}. However, if
739 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
742 The @code{switch-to-buffer} function is often used interactively, as
743 the binding of @kbd{C-x b}. It is also used frequently in programs. It
744 always returns @code{nil}.
747 @deffn Command switch-to-buffer-other-window buffer-or-name
748 This function makes @var{buffer-or-name} the current buffer and
749 displays it in a window not currently selected. It then selects that
750 window. The handling of the buffer is the same as in
751 @code{switch-to-buffer}.
753 The currently selected window is absolutely never used to do the job.
754 If it is the only window, then it is split to make a distinct window for
755 this purpose. If the selected window is already displaying the buffer,
756 then it continues to do so, but another window is nonetheless found to
757 display it in as well.
760 @defun pop-to-buffer buffer-or-name &optional other-window on-frame
761 This function makes @var{buffer-or-name} the current buffer and
762 switches to it in some window, preferably not the window previously
763 selected. The ``popped-to'' window becomes the selected window within
766 If the variable @code{pop-up-frames} is non-@code{nil},
767 @code{pop-to-buffer} looks for a window in any visible frame already
768 displaying the buffer; if there is one, it returns that window and makes
769 it be selected within its frame. If there is none, it creates a new
770 frame and displays the buffer in it.
772 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
773 operates entirely within the selected frame. (If the selected frame has
774 just a minibuffer, @code{pop-to-buffer} operates within the most
775 recently selected frame that was not just a minibuffer.)
777 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
778 be split to create a new window that is different from the original
779 window. For details, see @ref{Choosing Window}.
781 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
782 creates another window even if @var{buffer-or-name} is already visible
783 in the selected window. Thus @var{buffer-or-name} could end up
784 displayed in two windows. On the other hand, if @var{buffer-or-name} is
785 already displayed in the selected window and @var{other-window} is
786 @code{nil}, then the selected window is considered sufficient display
787 for @var{buffer-or-name}, so that nothing needs to be done.
789 All the variables that affect @code{display-buffer} affect
790 @code{pop-to-buffer} as well. @xref{Choosing Window}.
792 If @var{buffer-or-name} is a string that does not name an existing
793 buffer, a buffer by that name is created. The major mode for the new
794 buffer is set according to the variable @code{default-major-mode}.
795 @xref{Auto Major Mode}.
797 If @var{on-frame} is non-@code{nil}, it is the frame to pop to this
800 An example use of this function is found at the end of @ref{Filter
804 @deffn Command replace-buffer-in-windows buffer
805 This function replaces @var{buffer} with some other buffer in all
806 windows displaying it. The other buffer used is chosen with
807 @code{other-buffer}. In the usual applications of this function, you
808 don't care which other buffer is used; you just want to make sure that
809 @var{buffer} is no longer displayed.
811 This function returns @code{nil}.
814 @node Choosing Window
815 @section Choosing a Window for Display
817 This section describes the basic facility that chooses a window to
818 display a buffer in---@code{display-buffer}. All the higher-level
819 functions and commands use this subroutine. Here we describe how to use
820 @code{display-buffer} and how to customize it.
822 @deffn Command display-buffer buffer-or-name &optional not-this-window
823 This command makes @var{buffer-or-name} appear in some window, like
824 @code{pop-to-buffer}, but it does not select that window and does not
825 make the buffer current. The identity of the selected window is
826 unaltered by this function.
828 If @var{not-this-window} is non-@code{nil}, it means to display the
829 specified buffer in a window other than the selected one, even if it is
830 already on display in the selected window. This can cause the buffer to
831 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
832 already being displayed in any window, that is good enough, so this
833 function does nothing.
835 @code{display-buffer} returns the window chosen to display
836 @var{buffer-or-name}.
838 Precisely how @code{display-buffer} finds or creates a window depends on
839 the variables described below.
843 @cindex dedicated window
844 A window can be marked as ``dedicated'' to a particular buffer.
845 Then XEmacs will not automatically change which buffer appears in the
846 window, such as @code{display-buffer} might normally do.
848 @defun window-dedicated-p window
849 This function returns @var{window}'s dedicated object, usually @code{t}
853 @defun set-window-buffer-dedicated window buffer
854 This function makes @var{window} display @var{buffer} and be dedicated
855 to that buffer. Then XEmacs will not automatically change which buffer
856 appears in @var{window}. If @var{buffer} is @code{nil}, this function makes
857 @var{window} not be dedicated (but doesn't change which buffer appears
861 @defopt pop-up-windows
862 This variable controls whether @code{display-buffer} makes new windows.
863 If it is non-@code{nil} and there is only one window, then that window
864 is split. If it is @code{nil}, then @code{display-buffer} does not
865 split the single window, but uses it whole.
868 @defopt split-height-threshold
869 This variable determines when @code{display-buffer} may split a window,
870 if there are multiple windows. @code{display-buffer} always splits the
871 largest window if it has at least this many lines. If the largest
872 window is not this tall, it is split only if it is the sole window and
873 @code{pop-up-windows} is non-@code{nil}.
877 @defopt pop-up-frames
878 This variable controls whether @code{display-buffer} makes new frames.
879 If it is non-@code{nil}, @code{display-buffer} looks for an existing
880 window already displaying the desired buffer, on any visible frame. If
881 it finds one, it returns that window. Otherwise it makes a new frame.
882 The variables @code{pop-up-windows} and @code{split-height-threshold} do
883 not matter if @code{pop-up-frames} is non-@code{nil}.
885 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
886 splits a window or reuses one.
888 @xref{Frames}, for more information.
892 @defvar pop-up-frame-function
893 This variable specifies how to make a new frame if @code{pop-up-frames}
896 Its value should be a function of no arguments. When
897 @code{display-buffer} makes a new frame, it does so by calling that
898 function, which should return a frame. The default value of the
899 variable is a function that creates a frame using properties from
900 @code{pop-up-frame-plist}.
903 @defvar pop-up-frame-plist
904 This variable holds a plist specifying frame properties used when
905 @code{display-buffer} makes a new frame. @xref{Frame Properties}, for
906 more information about frame properties.
909 @defvar special-display-buffer-names
910 A list of buffer names for buffers that should be displayed specially.
911 If the buffer's name is in this list, @code{display-buffer} handles the
914 By default, special display means to give the buffer a dedicated frame.
916 If an element is a list, instead of a string, then the @sc{car} of the
917 list is the buffer name, and the rest of the list says how to create the
918 frame. There are two possibilities for the rest of the list. It can be
919 a plist, specifying frame properties, or it can contain a function and
920 arguments to give to it. (The function's first argument is always the
921 buffer to be displayed; the arguments from the list come after that.)
924 @defvar special-display-regexps
925 A list of regular expressions that specify buffers that should be
926 displayed specially. If the buffer's name matches any of the regular
927 expressions in this list, @code{display-buffer} handles the buffer
930 By default, special display means to give the buffer a dedicated frame.
932 If an element is a list, instead of a string, then the @sc{car} of the
933 list is the regular expression, and the rest of the list says how to
934 create the frame. See above, under @code{special-display-buffer-names}.
937 @defvar special-display-function
938 This variable holds the function to call to display a buffer specially.
939 It receives the buffer as an argument, and should return the window in
940 which it is displayed.
942 The default value of this variable is
943 @code{special-display-popup-frame}.
946 @defun special-display-popup-frame buffer
947 This function makes @var{buffer} visible in a frame of its own. If
948 @var{buffer} is already displayed in a window in some frame, it makes
949 the frame visible and raises it, to use that window. Otherwise, it
950 creates a frame that will be dedicated to @var{buffer}.
952 This function uses an existing window displaying @var{buffer} whether or
953 not it is in a frame of its own; but if you set up the above variables
954 in your init file, before @var{buffer} was created, then presumably the
955 window was previously made by this function.
958 @defopt special-display-frame-plist
959 This variable holds frame properties for
960 @code{special-display-popup-frame} to use when it creates a frame.
963 @defvar same-window-buffer-names
964 A list of buffer names for buffers that should be displayed in the
965 selected window. If the buffer's name is in this list,
966 @code{display-buffer} handles the buffer by switching to it in the
970 @defvar same-window-regexps
971 A list of regular expressions that specify buffers that should be
972 displayed in the selected window. If the buffer's name matches any of
973 the regular expressions in this list, @code{display-buffer} handles the
974 buffer by switching to it in the selected window.
978 @defvar display-buffer-function
979 This variable is the most flexible way to customize the behavior of
980 @code{display-buffer}. If it is non-@code{nil}, it should be a function
981 that @code{display-buffer} calls to do the work. The function should
982 accept two arguments, the same two arguments that @code{display-buffer}
983 received. It should choose or create a window, display the specified
984 buffer, and then return the window.
986 This hook takes precedence over all the other options and hooks
991 @cindex dedicated window
992 A window can be marked as ``dedicated'' to its buffer. Then
993 @code{display-buffer} does not try to use that window.
995 @defun window-dedicated-p window
996 This function returns @code{t} if @var{window} is marked as dedicated;
997 otherwise @code{nil}.
1000 @defun set-window-dedicated-p window flag
1001 This function marks @var{window} as dedicated if @var{flag} is
1002 non-@code{nil}, and nondedicated otherwise.
1006 @section Windows and Point
1007 @cindex window position
1008 @cindex window point
1009 @cindex position in window
1010 @cindex point in window
1012 Each window has its own value of point, independent of the value of
1013 point in other windows displaying the same buffer. This makes it useful
1014 to have multiple windows showing one buffer.
1018 The window point is established when a window is first created; it is
1019 initialized from the buffer's point, or from the window point of another
1020 window opened on the buffer if such a window exists.
1023 Selecting a window sets the value of point in its buffer to the window's
1024 value of point. Conversely, deselecting a window sets the window's
1025 value of point from that of the buffer. Thus, when you switch between
1026 windows that display a given buffer, the point value for the selected
1027 window is in effect in the buffer, while the point values for the other
1028 windows are stored in those windows.
1031 As long as the selected window displays the current buffer, the window's
1032 point and the buffer's point always move together; they remain equal.
1035 @xref{Positions}, for more details on buffer positions.
1038 As far as the user is concerned, point is where the cursor is, and
1039 when the user switches to another buffer, the cursor jumps to the
1040 position of point in that buffer.
1042 @defun window-point window
1043 This function returns the current position of point in @var{window}.
1044 For a nonselected window, this is the value point would have (in that
1045 window's buffer) if that window were selected.
1047 When @var{window} is the selected window and its buffer is also the
1048 current buffer, the value returned is the same as point in that buffer.
1050 Strictly speaking, it would be more correct to return the
1051 ``top-level'' value of point, outside of any @code{save-excursion}
1052 forms. But that value is hard to find.
1055 @defun set-window-point window position
1056 This function positions point in @var{window} at position
1057 @var{position} in @var{window}'s buffer.
1061 @section The Window Start Position
1063 Each window contains a marker used to keep track of a buffer position
1064 that specifies where in the buffer display should start. This position
1065 is called the @dfn{display-start} position of the window (or just the
1066 @dfn{start}). The character after this position is the one that appears
1067 at the upper left corner of the window. It is usually, but not
1068 inevitably, at the beginning of a text line.
1070 @defun window-start &optional window
1071 @cindex window top line
1072 This function returns the display-start position of window
1073 @var{window}. If @var{window} is @code{nil}, the selected window is
1083 When you create a window, or display a different buffer in it, the
1084 display-start position is set to a display-start position recently used
1085 for the same buffer, or 1 if the buffer doesn't have any.
1087 For a realistic example, see the description of @code{count-lines} in
1091 @defun window-end &optional window
1092 This function returns the position of the end of the display in window
1093 @var{window}. If @var{window} is @code{nil}, the selected window is
1096 Simply changing the buffer text or moving point does not update the
1097 value that @code{window-end} returns. The value is updated only when
1098 Emacs redisplays and redisplay actually finishes.
1100 If the last redisplay of @var{window} was preempted, and did not finish,
1101 Emacs does not know the position of the end of display in that window.
1102 In that case, this function returns a value that is not correct. In a
1103 future version, @code{window-end} will return @code{nil} in that case.
1105 in that case, this function returns @code{nil}. You can compute where
1106 the end of the window @emph{would} have been, if redisplay had finished,
1111 (goto-char (window-start window))
1112 (vertical-motion (1- (window-height window))
1119 @defun set-window-start window position &optional noforce
1120 This function sets the display-start position of @var{window} to
1121 @var{position} in @var{window}'s buffer. It returns @var{position}.
1123 The display routines insist that the position of point be visible when a
1124 buffer is displayed. Normally, they change the display-start position
1125 (that is, scroll the window) whenever necessary to make point visible.
1126 However, if you specify the start position with this function using
1127 @code{nil} for @var{noforce}, it means you want display to start at
1128 @var{position} even if that would put the location of point off the
1129 screen. If this does place point off screen, the display routines move
1130 point to the left margin on the middle line in the window.
1132 For example, if point @w{is 1} and you set the start of the window @w{to
1133 2}, then point would be ``above'' the top of the window. The display
1134 routines will automatically move point if it is still 1 when redisplay
1135 occurs. Here is an example:
1139 ;; @r{Here is what @samp{foo} looks like before executing}
1140 ;; @r{the @code{set-window-start} expression.}
1144 ---------- Buffer: foo ----------
1145 @point{}This is the contents of buffer foo.
1151 ---------- Buffer: foo ----------
1157 (1+ (window-start)))
1162 ;; @r{Here is what @samp{foo} looks like after executing}
1163 ;; @r{the @code{set-window-start} expression.}
1164 ---------- Buffer: foo ----------
1165 his is the contents of buffer foo.
1171 ---------- Buffer: foo ----------
1175 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1176 off screen at the next redisplay, then redisplay computes a new window-start
1177 position that works well with point, and thus @var{position} is not used.
1180 @defun pos-visible-in-window-p &optional position window
1181 This function returns @code{t} if @var{position} is within the range
1182 of text currently visible on the screen in @var{window}. It returns
1183 @code{nil} if @var{position} is scrolled vertically out of view. The
1184 argument @var{position} defaults to the current position of point;
1185 @var{window}, to the selected window. Here is an example:
1189 (or (pos-visible-in-window-p
1190 (point) (selected-window))
1195 The @code{pos-visible-in-window-p} function considers only vertical
1196 scrolling. If @var{position} is out of view only because @var{window}
1197 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
1198 @code{t}. @xref{Horizontal Scrolling}.
1201 @node Vertical Scrolling
1202 @section Vertical Scrolling
1203 @cindex vertical scrolling
1204 @cindex scrolling vertically
1206 Vertical scrolling means moving the text up or down in a window. It
1207 works by changing the value of the window's display-start location. It
1208 may also change the value of @code{window-point} to keep it on the
1211 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1212 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1213 you are looking through the window. Imagine that the text is
1214 written on a long roll of paper and that the scrolling commands move the
1215 paper up and down. Thus, if you are looking at text in the middle of a
1216 buffer and repeatedly call @code{scroll-down}, you will eventually see
1217 the beginning of the buffer.
1219 Some people have urged that the opposite convention be used: they
1220 imagine that the window moves over text that remains in place. Then
1221 ``down'' commands would take you to the end of the buffer. This view is
1222 more consistent with the actual relationship between windows and the
1223 text in the buffer, but it is less like what the user sees. The
1224 position of a window on the terminal does not move, and short scrolling
1225 commands clearly move the text up or down on the screen. We have chosen
1226 names that fit the user's point of view.
1228 The scrolling functions (aside from @code{scroll-other-window}) have
1229 unpredictable results if the current buffer is different from the buffer
1230 that is displayed in the selected window. @xref{Current Buffer}.
1232 @deffn Command scroll-up &optional count
1233 This function scrolls the text in the selected window upward
1234 @var{count} lines. If @var{count} is negative, scrolling is actually
1237 If @var{count} is @code{nil} (or omitted), then the length of scroll
1238 is @code{next-screen-context-lines} lines less than the usable height of
1239 the window (not counting its modeline).
1241 @code{scroll-up} returns @code{nil}.
1244 @deffn Command scroll-down &optional count
1245 This function scrolls the text in the selected window downward
1246 @var{count} lines. If @var{count} is negative, scrolling is actually
1249 If @var{count} is omitted or @code{nil}, then the length of the scroll
1250 is @code{next-screen-context-lines} lines less than the usable height of
1251 the window (not counting its mode line).
1253 @code{scroll-down} returns @code{nil}.
1256 @deffn Command scroll-other-window &optional count
1257 This function scrolls the text in another window upward @var{count}
1258 lines. Negative values of @var{count}, or @code{nil}, are handled
1259 as in @code{scroll-up}.
1261 You can specify a buffer to scroll with the variable
1262 @code{other-window-scroll-buffer}. When the selected window is the
1263 minibuffer, the next window is normally the one at the top left corner.
1264 You can specify a different window to scroll with the variable
1265 @code{minibuffer-scroll-window}. This variable has no effect when any
1266 other window is selected. @xref{Minibuffer Misc}.
1268 When the minibuffer is active, it is the next window if the selected
1269 window is the one at the bottom right corner. In this case,
1270 @code{scroll-other-window} attempts to scroll the minibuffer. If the
1271 minibuffer contains just one line, it has nowhere to scroll to, so the
1272 line reappears after the echo area momentarily displays the message
1273 ``Beginning of buffer''.
1277 @defvar other-window-scroll-buffer
1278 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1279 which buffer to scroll.
1283 This variable controls how scrolling is done automatically when point
1284 moves off the screen. If the value is zero, then redisplay scrolls the
1285 text to center point vertically in the window. If the value is a
1286 positive integer @var{n}, then redisplay brings point back on screen by
1287 scrolling @var{n} lines in either direction, if possible; otherwise, it
1288 centers point. The default value is zero.
1291 @defopt scroll-conservatively
1292 This variable controls how many lines Emacs tries to scroll before
1293 recentering. If you set it to a small number, then when you move point
1294 a short distance off the screen, XEmacs will scroll the screen just far
1295 enough to bring point back on screen, provided that does not exceed
1296 @code{scroll-conservatively} lines. This variable overrides the
1297 redisplay preemption.
1300 @defopt next-screen-context-lines
1301 The value of this variable is the number of lines of continuity to
1302 retain when scrolling by full screens. For example, @code{scroll-up}
1303 with an argument of @code{nil} scrolls so that this many lines at the
1304 bottom of the window appear instead at the top. The default value is
1308 @deffn Command recenter &optional count
1309 @cindex centering point
1310 This function scrolls the selected window to put the text where point
1311 is located at a specified vertical position within the window.
1313 If @var{count} is a nonnegative number, it puts the line containing
1314 point @var{count} lines down from the top of the window. If @var{count}
1315 is a negative number, then it counts upward from the bottom of the
1316 window, so that @minus{}1 stands for the last usable line in the window.
1317 If @var{count} is a non-@code{nil} list, then it stands for the line in
1318 the middle of the window.
1320 If @var{count} is @code{nil}, @code{recenter} puts the line containing
1321 point in the middle of the window, then clears and redisplays the entire
1324 When @code{recenter} is called interactively, @var{count} is the raw
1325 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1326 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1327 @var{count} to 4, which positions the current line four lines from the
1330 With an argument of zero, @code{recenter} positions the current line at
1331 the top of the window. This action is so handy that some people make a
1332 separate key binding to do this. For example,
1336 (defun line-to-top-of-window ()
1337 "Scroll current line to top of window.
1338 Replaces three keystroke sequence C-u 0 C-l."
1342 (global-set-key [kp-multiply] 'line-to-top-of-window)
1347 @node Horizontal Scrolling
1348 @section Horizontal Scrolling
1349 @cindex horizontal scrolling
1351 Because we read English first from top to bottom and second from left
1352 to right, horizontal scrolling is not like vertical scrolling. Vertical
1353 scrolling involves selection of a contiguous portion of text to display.
1354 Horizontal scrolling causes part of each line to go off screen. The
1355 amount of horizontal scrolling is therefore specified as a number of
1356 columns rather than as a position in the buffer. It has nothing to do
1357 with the display-start position returned by @code{window-start}.
1359 Usually, no horizontal scrolling is in effect; then the leftmost
1360 column is at the left edge of the window. In this state, scrolling to
1361 the right is meaningless, since there is no data to the left of the
1362 screen to be revealed by it; so this is not allowed. Scrolling to the
1363 left is allowed; it scrolls the first columns of text off the edge of
1364 the window and can reveal additional columns on the right that were
1365 truncated before. Once a window has a nonzero amount of leftward
1366 horizontal scrolling, you can scroll it back to the right, but only so
1367 far as to reduce the net horizontal scroll to zero. There is no limit
1368 to how far left you can scroll, but eventually all the text will
1369 disappear off the left edge.
1371 @deffn Command scroll-left count
1372 This function scrolls the selected window @var{count} columns to the
1373 left (or to the right if @var{count} is negative). The return value is
1374 the total amount of leftward horizontal scrolling in effect after the
1375 change---just like the value returned by @code{window-hscroll} (below).
1378 @deffn Command scroll-right count
1379 This function scrolls the selected window @var{count} columns to the
1380 right (or to the left if @var{count} is negative). The return value is
1381 the total amount of leftward horizontal scrolling in effect after the
1382 change---just like the value returned by @code{window-hscroll} (below).
1384 Once you scroll a window as far right as it can go, back to its normal
1385 position where the total leftward scrolling is zero, attempts to scroll
1386 any farther right have no effect.
1389 @defun window-hscroll &optional window
1390 This function returns the total leftward horizontal scrolling of
1391 @var{window}---the number of columns by which the text in @var{window}
1392 is scrolled left past the left margin.
1394 The value is never negative. It is zero when no horizontal scrolling
1395 has been done in @var{window} (which is usually the case).
1397 If @var{window} is @code{nil}, the selected window is used.
1415 @defun set-window-hscroll window columns
1416 This function sets the number of columns from the left margin that
1417 @var{window} is scrolled to the value of @var{columns}. The argument
1418 @var{columns} should be zero or positive; if not, it is taken as zero.
1420 The value returned is @var{columns}.
1424 (set-window-hscroll (selected-window) 10)
1430 Here is how you can determine whether a given position @var{position}
1431 is off the screen due to horizontal scrolling:
1435 (defun hscroll-on-screen (window position)
1437 (goto-char position)
1439 (>= (- (current-column) (window-hscroll window)) 0)
1440 (< (- (current-column) (window-hscroll window))
1441 (window-width window)))))
1444 @node Size of Window
1445 @section The Size of a Window
1447 @cindex size of window
1449 An Emacs window is rectangular, and its size information consists of
1450 the height (in lines or pixels) and the width (in character positions
1451 or pixels). The modeline is included in the height. The pixel
1452 width and height values include scrollbars and margins, while the
1453 line/character-position values do not.
1455 Note that the height in lines, and the width in characters, are
1456 determined by dividing the corresponding pixel value by the height or
1457 width of the default font in that window (if this is a variable-width
1458 font, the average width is used). The resulting values may or may not
1459 represent the actual number of lines in the window, or the actual number
1460 of character positions in any particular line, esp. if there are pixmaps
1461 or various different fonts in the window.
1463 The following functions return size information about a window:
1465 @defun window-height &optional window
1466 This function returns the number of lines in @var{window}, including
1467 its modeline but not including the horizontal scrollbar, if any (this
1468 is different from @code{window-pixel-height}). If @var{window} is
1469 @code{nil}, the function uses the selected window.
1477 (split-window-vertically)
1478 @result{} #<window on "windows.texi" 0x679b>
1487 @defun window-width &optional window
1488 This function returns the number of columns in @var{window}, not
1489 including any left margin, right margin, or vertical scrollbar (this is
1490 different from @code{window-pixel-width}). If @var{window} is
1491 @code{nil}, the function uses the selected window.
1503 (split-window-horizontally)
1504 @result{} #<window on "windows.texi" 0x7538>
1513 Note that after splitting the window into two side-by-side windows,
1514 the width of each window is less the half the width of the original
1515 window because a vertical scrollbar appeared between the windows,
1516 occupying two columns worth of space. Also, the height shrunk by
1517 one because horizontal scrollbars appeared that weren't there
1518 before. (Horizontal scrollbars appear only when lines are
1519 truncated, not when they wrap. This is usually the case for
1520 horizontally split windows but not for full-frame windows. You
1521 can change this using the variables @code{truncate-lines} and
1522 @code{truncate-partial-width-windows}.)
1524 @defun window-pixel-height &optional window
1525 This function returns the height of @var{window} in pixels, including
1526 its modeline and horizontal scrollbar, if any. If @var{window} is
1527 @code{nil}, the function uses the selected window.
1531 (window-pixel-height)
1535 (split-window-vertically)
1536 @result{} #<window on "windows.texi" 0x68a6>
1539 (window-pixel-height)
1545 @defun window-pixel-width &optional window
1546 This function returns the width of @var{window} in pixels, including
1547 any left margin, right margin, or vertical scrollbar that may be
1548 displayed alongside it. If @var{window} is @code{nil}, the function
1549 uses the selected window.
1553 (window-pixel-width)
1557 (window-pixel-height)
1561 (split-window-horizontally)
1562 @result{} #<window on "windows.texi" 0x7538>
1565 (window-pixel-width)
1569 (window-pixel-height)
1575 @defun window-text-area-pixel-height &optional window
1576 This function returns the height in pixels of the text displaying
1577 portion of @var{window}, which defaults to the selected window. Unlike
1578 @code{window-pixel-height}, the space occupied by the modeline and
1579 horizontal scrollbar, if any, is not counted.
1582 @defun window-text-area-pixel-width &optional window
1583 This function returns the width in pixels of the text displaying
1584 portion of @var{window}, which defaults to the selected window. Unlike
1585 @code{window-pixel-width}, the space occupied by the vertical scrollbar
1586 and divider, if any, is not counted.
1589 @defun window-displayed-text-pixel-height &optional window noclipped
1590 This function returns the height in pixels of the text displayed in
1591 @var{window}, which defaults to the selected window. Unlike
1592 @code{window-text-area-pixel-height}, any blank space below the
1593 end of the buffer is not included. If optional argument @var{noclipped}
1594 is non-@code{nil}, any space occupied by clipped lines will not be
1598 @node Position of Window
1599 @section The Position of a Window
1600 @cindex window position
1601 @cindex position of window
1603 XEmacs provides functions to determine the absolute location of windows
1604 within a frame, and the relative location of a window in comparison to
1605 other windows in the same frame.
1607 @defun window-pixel-edges &optional window
1608 This function returns a list of the pixel edge coordinates of
1609 @var{window}. If @var{window} is @code{nil}, the selected window is
1612 The order of the list is @code{(@var{left} @var{top} @var{right}
1613 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1614 the frame. The element @var{right} of the value is one more than the
1615 rightmost pixel used by @var{window} (including any left margin, right
1616 margin, or vertical scrollbar displayed alongside it), and
1617 @var{bottom} is one more than the bottommost pixel used by @var{window}
1618 (including any modeline or horizontal scrollbar displayed above
1619 or below it). The frame area does not include any frame menubars or
1620 toolbars that may be displayed; thus, for example, if there is only
1621 one window on the frame, the values for @var{left} and @var{top} will
1624 If @var{window} is at the upper left corner of its frame, @var{right}
1625 and @var{bottom} are the same as the values returned by
1626 @code{(window-pixel-width)} and @code{(window-pixel-height)}
1627 respectively, and @var{top} and @var{bottom} are zero.
1630 There is no longer a function @code{window-edges} because it does not
1631 make sense in a world with variable-width and variable-height lines,
1632 as are allowed in XEmacs.
1634 @defun window-highest-p window
1635 This function returns non-@code{nil} if @var{window} is along the
1639 @defun window-lowest-p window
1640 This function returns non-@code{nil} if @var{window} is along the
1641 bottom of its frame.
1644 @defun window-text-area-pixel-edges &optional window
1645 This function allows one to determine the location of the
1646 text-displaying portion of @var{window}, which defaults to the selected
1647 window, with respect to the top left corner of the window. It returns
1648 a list of integer pixel positions @code{(left top right bottom)}, all
1649 relative to @code{(0,0)} at the top left corner of the window.
1652 @node Resizing Windows
1653 @section Changing the Size of a Window
1654 @cindex window resizing
1655 @cindex changing window size
1656 @cindex window size, changing
1658 The window size functions fall into two classes: high-level commands
1659 that change the size of windows and low-level functions that access
1660 window size. XEmacs does not permit overlapping windows or gaps between
1661 windows, so resizing one window affects other windows.
1663 @deffn Command enlarge-window size &optional horizontal window
1664 This function makes the selected window @var{size} lines taller,
1665 stealing lines from neighboring windows. It takes the lines from one
1666 window at a time until that window is used up, then takes from another.
1667 If a window from which lines are stolen shrinks below
1668 @code{window-min-height} lines, that window disappears.
1670 If @var{horizontal} is non-@code{nil}, this function makes
1671 @var{window} wider by @var{size} columns, stealing columns instead of
1672 lines. If a window from which columns are stolen shrinks below
1673 @code{window-min-width} columns, that window disappears.
1675 If the requested size would exceed that of the window's frame, then the
1676 function makes the window occupy the entire height (or width) of the
1679 If @var{size} is negative, this function shrinks the window by
1680 @minus{}@var{size} lines or columns. If that makes the window smaller
1681 than the minimum size (@code{window-min-height} and
1682 @code{window-min-width}), @code{enlarge-window} deletes the window.
1684 If @var{window} is non-@code{nil}, it specifies a window to change
1685 instead of the selected window.
1687 @code{enlarge-window} returns @code{nil}.
1690 @deffn Command enlarge-window-horizontally columns
1691 This function makes the selected window @var{columns} wider.
1692 It could be defined as follows:
1696 (defun enlarge-window-horizontally (columns)
1697 (enlarge-window columns t))
1702 @deffn Command enlarge-window-pixels count &optional side window
1703 This function makes the selected window @var{count} pixels larger. When
1704 called from Lisp, optional second argument @var{side} non-@code{nil}
1705 means to grow sideways @var{count} pixels, and optional third argument
1706 @var{window} specifies the window to change instead of the selected
1710 @deffn Command shrink-window size &optional horizontal window
1711 This function is like @code{enlarge-window} but negates the argument
1712 @var{size}, making the selected window smaller by giving lines (or
1713 columns) to the other windows. If the window shrinks below
1714 @code{window-min-height} or @code{window-min-width}, then it disappears.
1716 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
1719 If @var{window} is non-@code{nil}, it specifies a window to change
1720 instead of the selected window.
1723 @deffn Command shrink-window-horizontally columns
1724 This function makes the selected window @var{columns} narrower.
1725 It could be defined as follows:
1729 (defun shrink-window-horizontally (columns)
1730 (shrink-window columns t))
1735 @deffn Command shrink-window-pixels count &optional side window
1736 This function makes the selected window @var{count} pixels smaller.
1737 When called from Lisp, optional second argument @var{side}
1738 non-@code{nil} means to shrink sideways @var{count} pixels, and optional
1739 third argument @var{window} specifies the window to change instead of
1740 the selected window.
1743 @cindex minimum window size
1744 The following two variables constrain the window-size-changing
1745 functions to a minimum height and width.
1747 @defopt window-min-height
1748 The value of this variable determines how short a window may become
1749 before it is automatically deleted. Making a window smaller than
1750 @code{window-min-height} automatically deletes it, and no window may be
1751 created shorter than this. The absolute minimum height is two (allowing
1752 one line for the mode line, and one line for the buffer display).
1753 Actions that change window sizes reset this variable to two if it is
1754 less than two. The default value is 4.
1757 @defopt window-min-width
1758 The value of this variable determines how narrow a window may become
1759 before it automatically deleted. Making a window smaller than
1760 @code{window-min-width} automatically deletes it, and no window may be
1761 created narrower than this. The absolute minimum width is one; any
1762 value below that is ignored. The default value is 10.
1765 @c This is not yet implemented. Why is it "documented"?
1766 @defvar window-size-change-functions
1767 This variable holds a list of functions to be called if the size of any
1768 window changes for any reason. The functions are called just once per
1769 redisplay, and just once for each frame on which size changes have
1772 Each function receives the frame as its sole argument. There is no
1773 direct way to find out which windows changed size, or precisely how;
1774 however, if your size-change function keeps track, after each change, of
1775 the windows that interest you, you can figure out what has changed by
1776 comparing the old size data with the new.
1778 Creating or deleting windows counts as a size change, and therefore
1779 causes these functions to be called. Changing the frame size also
1780 counts, because it changes the sizes of the existing windows.
1782 It is not a good idea to use @code{save-window-excursion} in these
1783 functions, because that always counts as a size change, and it would
1784 cause these functions to be called over and over. In most cases,
1785 @code{save-selected-window} is what you need here.
1788 @node Window Configurations
1789 @section Window Configurations
1790 @cindex window configurations
1791 @cindex saving window information
1793 A @dfn{window configuration} records the entire layout of a
1794 frame---all windows, their sizes, which buffers they contain, what part
1795 of each buffer is displayed, and the values of point and the mark. You
1796 can bring back an entire previous layout by restoring a window
1797 configuration previously saved.
1799 If you want to record all frames instead of just one, use a frame
1800 configuration instead of a window configuration. @xref{Frame
1803 @defun current-window-configuration
1804 This function returns a new object representing XEmacs's current window
1805 configuration, namely the number of windows, their sizes and current
1806 buffers, which window is the selected window, and for each window the
1807 displayed buffer, the display-start position, and the positions of point
1808 and the mark. An exception is made for point in the current buffer,
1809 whose value is not saved.
1812 @defun set-window-configuration configuration
1813 This function restores the configuration of XEmacs's windows and
1814 buffers to the state specified by @var{configuration}. The argument
1815 @var{configuration} must be a value that was previously returned by
1816 @code{current-window-configuration}.
1818 This function always counts as a window size change and triggers
1819 execution of the @code{window-size-change-functions}. (It doesn't know
1820 how to tell whether the new configuration actually differs from the old
1823 Here is a way of using this function to get the same effect
1824 as @code{save-window-excursion}:
1828 (let ((config (current-window-configuration)))
1830 (progn (split-window-vertically nil)
1832 (set-window-configuration config)))
1837 @defspec save-window-excursion forms@dots{}
1838 This special form records the window configuration, executes @var{forms}
1839 in sequence, then restores the earlier window configuration. The window
1840 configuration includes the value of point and the portion of the buffer
1841 that is visible. It also includes the choice of selected window.
1842 However, it does not include the value of point in the current buffer;
1843 use @code{save-excursion} if you wish to preserve that.
1845 Don't use this construct when @code{save-selected-window} is all you need.
1847 Exit from @code{save-window-excursion} always triggers execution of the
1848 @code{window-size-change-functions}. (It doesn't know how to tell
1849 whether the restored configuration actually differs from the one in
1850 effect at the end of the @var{forms}.)
1852 The return value is the value of the final form in @var{forms}.
1858 @result{} #<window 25 on control.texi>
1861 (setq w (selected-window))
1862 @result{} #<window 19 on control.texi>
1865 (save-window-excursion
1866 (delete-other-windows w)
1867 (switch-to-buffer "foo")
1869 @result{} do-something
1870 ;; @r{The frame is now split again.}
1875 @defun window-configuration-p object
1876 This function returns @code{t} if @var{object} is a window configuration.
1879 Primitives to look inside of window configurations would make sense,
1880 but none are implemented. It is not clear they are useful enough to be