2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/windows.info
8 @node Windows, Frames, Buffers, Top
11 This chapter describes most of the functions and variables related to
12 Emacs windows. See @ref{Display}, for information on how text is
16 * Basic Windows:: Basic information on using windows.
17 * Splitting Windows:: Splitting one window into two windows.
18 * Deleting Windows:: Deleting a window gives its space to other
20 * Selecting Windows:: The selected window is the one that you edit
22 * Cyclic Window Ordering:: Moving around the existing windows.
23 * Buffers and Windows:: Each window displays the contents of a buffer.
24 * Displaying Buffers:: Higher-lever functions for displaying a buffer
25 and choosing a window for it.
26 * Choosing Window:: How to choose a window for displaying a buffer.
27 * Window Point:: Each window has its own location of point.
28 * Window Start:: The display-start position controls which text
29 is on-screen in the window.
30 * Vertical Scrolling:: Moving text up and down in the window.
31 * Horizontal Scrolling:: Moving text sideways on the window.
32 * Size of Window:: Accessing the size of a window.
33 * Position of Window:: Accessing the position of a window.
34 * Resizing Windows:: Changing the size of a window.
35 * Window Configurations:: Saving and restoring the state of the screen.
36 * Window Configuration Hook:: Running code when the window configuration
42 @section Basic Concepts of Emacs Windows
44 @cindex selected window
46 A @dfn{window} in SXEmacs is the physical area of the screen in which a
47 buffer is displayed. The term is also used to refer to a Lisp object that
48 represents that screen area in SXEmacs Lisp. It should be
49 clear from the context which is meant.
51 SXEmacs groups windows into frames. A frame represents an area of
52 screen available for SXEmacs to use. Each frame always contains at least
53 one window, but you can subdivide it vertically or horizontally into
54 multiple nonoverlapping SXEmacs windows.
56 In each frame, at any time, one and only one window is designated as
57 @dfn{selected within the frame}. The frame's cursor appears in that
58 window. At any time, one frame is the selected frame; and the window
59 selected within that frame is @dfn{the selected window}. The selected
60 window's buffer is usually the current buffer (except when
61 @code{set-buffer} has been used). @xref{Current Buffer}.
63 For practical purposes, a window exists only while it is displayed in
64 a frame. Once removed from the frame, the window is effectively deleted
65 and should not be used, @emph{even though there may still be references
66 to it} from other Lisp objects. Restoring a saved window configuration
67 is the only way for a window no longer on the screen to come back to
68 life. (@xref{Deleting Windows}.)
70 Each window has the following attributes:
83 window edges with respect to the frame or screen
86 the buffer it displays
89 position within the buffer at the upper left of the window
92 amount of horizontal scrolling, in columns
101 how recently the window was selected
104 @cindex multiple windows
105 Users create multiple windows so they can look at several buffers at
106 once. Lisp libraries use multiple windows for a variety of reasons, but
107 most often to display related information. In Rmail, for example, you
108 can move through a summary buffer in one window while the other window
109 shows messages one at a time as they are reached.
111 The meaning of ``window'' in SXEmacs is similar to what it means in the
112 context of general-purpose window systems such as X, but not identical.
113 The X Window System places X windows on the screen; SXEmacs uses one or
114 more X windows as frames, and subdivides them into
115 SXEmacs windows. When you use SXEmacs on a character-only terminal,
116 SXEmacs treats the whole terminal screen as one frame.
118 @cindex terminal frame
119 @cindex frame of terminal
120 @cindex tiled windows
121 Most window systems support arbitrarily located overlapping windows.
122 In contrast, SXEmacs windows are @dfn{tiled}; they never overlap, and
123 together they fill the whole screen or frame. Because of the way
124 in which SXEmacs creates new windows and resizes them, you can't create
125 every conceivable tiling of windows on an SXEmacs frame. @xref{Splitting
126 Windows}, and @ref{Size of Window}.
128 @xref{Display}, for information on how the contents of the
129 window's buffer are displayed in the window.
131 @defun windowp object
132 This function returns @code{t} if @var{object} is a window.
136 @node Splitting Windows
137 @section Splitting Windows
138 @cindex splitting windows
139 @cindex window splitting
141 The functions described here are the primitives used to split a window
142 into two windows. Two higher level functions sometimes split a window,
143 but not always: @code{pop-to-buffer} and @code{display-buffer}
144 (@pxref{Displaying Buffers}).
146 The functions described here do not accept a buffer as an argument.
147 The two ``halves'' of the split window initially display the same buffer
148 previously visible in the window that was split.
150 @defun one-window-p &optional nomini which-frames which-devices
151 This function returns non-@code{nil} if there is only one window. The
152 argument @var{nomini}, if non-@code{nil}, means don't count the
153 minibuffer even if it is active; otherwise, the minibuffer window is
154 included, if active, in the total number of windows which is compared
157 The remaining arguments controls which set of windows are counted, as
158 with @code{next-window}.
161 @deffn Command split-window &optional window size horizontal
162 This function splits @var{window} into two windows. The original
163 window @var{window} remains the selected window, but occupies only
164 part of its former screen area. The rest is occupied by a newly created
165 window which is returned as the value of this function.
167 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
168 two side by side windows. The original window @var{window} keeps the
169 leftmost @var{size} columns, and gives the rest of the columns to the
170 new window. Otherwise, it splits into windows one above the other, and
171 @var{window} keeps the upper @var{size} lines and gives the rest of the
172 lines to the new window. The original window is therefore the
173 left-hand or upper of the two, and the new window is the right-hand or
176 If @var{window} is omitted or @code{nil}, then the selected window is
177 split. If @var{size} is omitted or @code{nil}, then @var{window} is
178 divided evenly into two parts. (If there is an odd line, it is
179 allocated to the new window.) When @code{split-window} is called
180 interactively, all its arguments are @code{nil}.
182 The following example starts with one window on a frame that is 50
183 lines high by 80 columns wide; then the window is split.
187 (setq w (selected-window))
188 @result{} #<window 8 on windows.texi>
189 (window-edges) ; @r{Edges in order:}
190 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
194 ;; @r{Returns window created}
195 (setq w2 (split-window w 15))
196 @result{} #<window 28 on windows.texi>
200 @result{} (0 15 80 50) ; @r{Bottom window;}
205 @result{} (0 0 80 15) ; @r{Top window}
209 The frame looks like this:
225 Next, the top window is split horizontally:
229 (setq w3 (split-window w 35 t))
230 @result{} #<window 32 on windows.texi>
234 @result{} (35 0 80 15) ; @r{Left edge at column 35}
238 @result{} (0 0 35 15) ; @r{Right edge at column 35}
242 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
247 Now, the screen looks like this:
264 Normally, SXEmacs indicates the border between two side-by-side windows
265 with a scroll bar (@pxref{X Frame Properties,Scroll Bars}) or @samp{|}
266 characters. The display table can specify alternative border
267 characters; see @ref{Display Tables}.
270 @deffn Command split-window-vertically &optional size
271 This function splits the selected window into two windows, one above
272 the other, leaving the selected window with @var{size} lines.
274 This function is simply an interface to @code{split-window}.
275 Here is the complete function definition for it:
279 (defun split-window-vertically (&optional arg)
280 "Split current window into two windows, one above the other."
282 (split-window nil (and arg (prefix-numeric-value arg))))
287 @deffn Command split-window-horizontally &optional size
288 This function splits the selected window into two windows
289 side-by-side, leaving the selected window with @var{size} columns.
291 This function is simply an interface to @code{split-window}. Here is
292 the complete definition for @code{split-window-horizontally} (except for
293 part of the documentation string):
297 (defun split-window-horizontally (&optional arg)
298 "Split selected window into two windows, side by side..."
300 (split-window nil (and arg (prefix-numeric-value arg)) t))
306 @node Deleting Windows
307 @section Deleting Windows
308 @cindex deleting windows
310 A window remains visible on its frame unless you @dfn{delete} it by
311 calling certain functions that delete windows. A deleted window cannot
312 appear on the screen, but continues to exist as a Lisp object until
313 there are no references to it. There is no way to cancel the deletion
314 of a window aside from restoring a saved window configuration
315 (@pxref{Window Configurations}). Restoring a window configuration also
316 deletes any windows that aren't part of that configuration.
318 When you delete a window, the space it took up is given to one
319 adjacent sibling. (In Emacs version 18, the space was divided evenly
320 among all the siblings.)
323 @defun window-live-p window
324 This function returns @code{nil} if @var{window} is deleted, and
327 @strong{Warning:} Erroneous information or fatal errors may result from
328 using a deleted window as if it were live.
331 @deffn Command delete-window &optional window force
332 This function removes @var{window} from the display. If @var{window} is
333 omitted, then the selected window is deleted. If window is the only one
334 on its frame, the frame is deleted as well.
336 Normally, you cannot delete the last non-minibuffer-only frame (you must
337 use @code{save-buffers-kill-emacs} or @code{kill-emacs}); an error is
338 signaled instead. However, if optional second argument @var{force} is
339 non-@code{nil}, you can delete the last frame. (This will automatically
340 call @code{save-buffers-kill-emacs}.)
342 This function returns @code{nil}.
344 When @code{delete-window} is called interactively, the selected window
348 @deffn Command delete-other-windows &optional window
349 This function makes @var{window} the only window on its frame, by
350 deleting the other windows in that frame. If @var{window} is omitted or
351 @code{nil}, then the selected window is used by default.
353 The result is @code{nil}.
356 @deffn Command delete-windows-on buffer &optional which-frames which-devices
357 This function deletes all windows showing @var{buffer}. If there are
358 no windows showing @var{buffer}, it does nothing.
360 @code{delete-windows-on} operates frame by frame. If a frame has
361 several windows showing different buffers, then those showing
362 @var{buffer} are removed, and the others expand to fill the space. If
363 all windows in some frame are showing @var{buffer} (including the case
364 where there is only one window), then the frame reverts to having a
365 single window showing another buffer chosen with @code{other-buffer}.
366 @xref{The Buffer List}.
368 The argument @var{which-frames} controls which frames to operate on:
372 Delete all windows showing @var{buffer} in any frame.
375 Delete only windows showing @var{buffer} in the selected frame.
378 Delete all windows showing @var{buffer} in any visible frame.
381 Delete all windows showing @var{buffer} in any visible frame.
384 If it is a frame, delete all windows showing @var{buffer} in that frame.
387 @strong{Warning:} This is similar to, but not identical to, the meaning
388 of the @var{which-frames} argument to @code{next-window}; the meanings
389 of @code{nil} and @code{t} are reversed.
391 The optional argument @var{which-devices} further clarifies on which
392 devices to search for frames as specified by @var{which-frames}.
393 This value is only meaningful if @var{which-frames} is not @code{t}.
397 Consider all devices on the selected console.
400 Consider only the one device @var{device}.
403 Consider all devices on @var{console}.
405 @item @var{device-type}
406 Consider all devices with device type @var{device-type}.
408 @item @code{window-system}
409 Consider all devices on window system consoles.
412 Consider all devices without restriction.
415 This function always returns @code{nil}.
419 @node Selecting Windows
420 @section Selecting Windows
421 @cindex selecting windows
423 When a window is selected, the buffer in the window becomes the current
424 buffer, and the cursor will appear in it.
426 @defun selected-window &optional device
427 This function returns the selected window. This is the window in
428 which the cursor appears and to which many commands apply. Each
429 separate device can have its own selected window, which is remembered
430 as focus changes from device to device. Optional argument @var{device}
431 specifies which device to return the selected window for, and defaults
432 to the selected device.
435 @defun select-window window &optional norecord
436 This function makes @var{window} the selected window. The cursor then
437 appears in @var{window} (on redisplay). The buffer being displayed in
438 @var{window} is immediately designated the current buffer.
440 If optional argument @var{norecord} is non-@code{nil} then the global
441 and per-frame buffer orderings are not modified, as by the function
442 @code{record-buffer}.
444 The return value is @var{window}.
448 (setq w (next-window))
450 @result{} #<window 65 on windows.texi>
455 @defspec save-selected-window forms@dots{}
456 This special form records the selected window, executes @var{forms} in
457 sequence, then restores the earlier selected window. It does not save
458 or restore anything about the sizes, arrangement or contents of windows;
459 therefore, if the @var{forms} change them, 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 which-frames which-devices
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 By default, only the windows in the selected frame are considered.
475 The optional argument @var{which-frames} changes this behavior.
476 Here are the possible values and their meanings:
480 Consider all the windows in the selected windows's frame, plus the
481 minibuffer used by that frame even if it lies in some other frame.
484 Consider all windows in all existing frames.
487 Consider all windows in all visible frames. (To get useful results, you
488 must ensure @var{window} is in a visible frame.)
491 Consider all windows in all visible or iconified frames.
494 Consider all windows on frame @var{frame}.
497 Consider precisely the windows in the selected window's frame, and no others.
500 The optional argument @var{which-devices} further clarifies on which
501 devices to search for frames as specified by @var{which-frames}.
502 This value is only meaningful if @var{which-frames} is non-@code{nil}.
506 Consider all devices on the selected console.
509 Consider only the one device @var{device}.
512 Consider all devices on @var{console}.
514 @item @var{device-type}
515 Consider all devices with device type @var{device-type}.
517 @item @code{window-system}
518 Consider all devices on window system consoles.
521 Consider all devices without restriction.
526 @defun get-largest-window &optional which-frames which-devices
527 This function returns the window with the largest area (height times
528 width). If there are no side-by-side windows, then this is the window
529 with the most lines. A minibuffer window is never a candidate.
531 If there are two windows of the same size, then the function returns
532 the window that is first in the cyclic ordering of windows (see
533 following section), starting from the selected window.
535 The remaining arguments control which set of windows are considered.
536 See @code{next-window}, above.
540 @node Cyclic Window Ordering
541 @section Cyclic Ordering of Windows
542 @cindex cyclic ordering of windows
543 @cindex ordering of windows, cyclic
544 @cindex window ordering, cyclic
546 When you use the command @kbd{C-x o} (@code{other-window}) to select
547 the next window, it moves through all the windows on the screen in a
548 specific cyclic order. For any given configuration of windows, this
549 order never varies. It is called the @dfn{cyclic ordering of windows}.
551 This ordering generally goes from top to bottom, and from left to
552 right. But it may go down first or go right first, depending on the
553 order in which the windows were split.
555 If the first split was vertical (into windows one above each other),
556 and then the subwindows were split horizontally, then the ordering is
557 left to right in the top of the frame, and then left to right in the
558 next lower part of the frame, and so on. If the first split was
559 horizontal, the ordering is top to bottom in the left part, and so on.
560 In general, within each set of siblings at any level in the window tree,
561 the order is left to right, or top to bottom.
563 @defun next-window &optional window minibuf which-frames which-devices
564 @cindex minibuffer window
565 This function returns the window following @var{window} in the cyclic
566 ordering of windows. This is the window that @kbd{C-x o} would select
567 if typed when @var{window} is selected. If @var{window} is the only
568 window visible, then this function returns @var{window}. If omitted,
569 @var{window} defaults to the selected window.
571 The value of the argument @var{minibuf} determines whether the
572 minibuffer is included in the window order. Normally, when
573 @var{minibuf} is @code{nil}, the minibuffer is included if it is
574 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
575 window is active while the minibuffer is in use. @xref{Minibuffers}.)
577 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
578 minibuffer window even if it is not active.
580 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
581 window is not included even if it is active.
583 By default, only the windows in the selected frame are considered.
584 The optional argument @var{which-frames} changes this behavior.
585 Here are the possible values and their meanings:
589 Consider all the windows in @var{window}'s frame, plus the minibuffer
590 used by that frame even if it lies in some other frame.
593 Consider all windows in all existing frames.
596 Consider all windows in all visible frames. (To get useful results, you
597 must ensure @var{window} is in a visible frame.)
600 Consider all windows in all visible or iconified frames.
603 Consider all windows on frame @var{frame}.
606 Consider precisely the windows in @var{window}'s frame, and no others.
609 The optional argument @var{which-devices} further clarifies on which
610 devices to search for frames as specified by @var{which-frames}.
611 This value is only meaningful if @var{which-frames} is non-@code{nil}.
615 Consider all devices on the selected console.
618 Consider only the one device @var{device}.
621 Consider all devices on @var{console}.
623 @item @var{device-type}
624 Consider all devices with device type @var{device-type}.
626 @item @code{window-system}
627 Consider all devices on window system consoles.
630 Consider all devices without restriction.
633 If you use consistent values for @var{minibuf}, @var{which-frames}, and
634 @var{which-devices}, you can use @code{next-window} to iterate through the
635 entire cycle of acceptable windows, eventually ending up back at the
636 window you started with. @code{previous-window} traverses the same
637 cycle, in the reverse order.
639 This example assumes there are two windows, both displaying the
640 buffer @samp{windows.texi}:
645 @result{} #<window 56 on windows.texi>
648 (next-window (selected-window))
649 @result{} #<window 52 on windows.texi>
652 (next-window (next-window (selected-window)))
653 @result{} #<window 56 on windows.texi>
658 @defun previous-window &optional window minibuf which-frames which-devices
659 This function returns the window preceding @var{window} in the cyclic
660 ordering of windows. The other arguments specify which windows to
661 include in the cycle, as in @code{next-window}.
664 @deffn Command other-window count &optional which-frames which-devices
665 This function selects the @var{count}th following window in the cyclic order.
666 If @var{count} is negative, then it selects the @minus{}@var{count}th
667 preceding window. It returns @code{nil}.
669 In an interactive call, @var{count} is the numeric prefix argument.
671 The other arguments specify which windows to include in the cycle, as in
675 @defun walk-windows function &optional minibuf which-frames which-devices
676 This function cycles through all windows, calling @code{function}
677 once for each window with the window as its sole argument.
679 The other arguments specify which windows to cycle through, as in
684 @node Buffers and Windows
685 @section Buffers and Windows
686 @cindex examining windows
687 @cindex windows, controlling precisely
688 @cindex buffers, controlled in windows
690 This section describes low-level functions to examine windows or to
691 display buffers in windows in a precisely controlled fashion.
693 See the following section for
696 @xref{Displaying Buffers}, for
698 related functions that find a window to use and specify a buffer for it.
699 The functions described there are easier to use than these, but they
700 employ heuristics in choosing or creating a window; use these functions
701 when you need complete control.
703 @defun set-window-buffer window buffer-or-name &optional norecord
704 This function makes @var{window} display @var{buffer-or-name} as its
705 contents. @var{buffer-or-name} can be a buffer or a buffer name.
707 With non-@code{nil} optional argument @var{norecord}, do not modify the
708 global or per-frame buffer ordering.
710 This function returns @code{nil}.
714 (set-window-buffer (selected-window) "foo")
720 @defun window-buffer &optional window
721 This function returns the buffer that @var{window} is displaying. If
722 @var{window} is omitted, this function returns the buffer for the
728 @result{} #<buffer windows.texi>
733 @defun get-buffer-window buffer-or-name &optional which-frames which-devices
734 This function returns a window currently displaying
735 @var{buffer-or-name}, or @code{nil} if there is none. If there are
736 several such windows, then the function returns the first one in the
737 cyclic ordering of windows, starting from the selected window.
738 @xref{Cyclic Window Ordering}.
740 The remaining arguments control which windows to consider. They have
741 the same meaning as for @code{next-window}.
745 @node Displaying Buffers
746 @section Displaying Buffers in Windows
747 @cindex switching to a buffer
748 @cindex displaying a buffer
750 In this section we describe convenient functions that choose a window
751 automatically and use it to display a specified buffer. These functions
752 can also split an existing window in certain circumstances. We also
753 describe variables that parameterize the heuristics used for choosing a
756 See the preceding section for
759 @xref{Buffers and Windows}, for
761 low-level functions that give you more precise control.
763 Do not use the functions in this section in order to make a buffer
764 current so that a Lisp program can access or modify it; they are too
765 drastic for that purpose, since they change the display of buffers in
766 windows, which is gratuitous and will surprise the user. Instead, use
767 @code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
768 (@pxref{Excursions}), which designate buffers as current for programmed
769 access without affecting the display of buffers in windows.
771 @deffn Command switch-to-buffer buffer-or-name &optional norecord
772 This function makes @var{buffer-or-name} the current buffer, and also
773 displays the buffer in the selected window. This means that a human can
774 see the buffer and subsequent keyboard commands will apply to it.
775 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
776 the current buffer but does not display it in the selected window.
777 @xref{Current Buffer}.
779 If @var{buffer-or-name} does not identify an existing buffer, then a new
780 buffer by that name is created. The major mode for the new buffer is
781 set according to the variable @code{default-major-mode}. @xref{Auto
784 Normally the specified buffer is put at the front of the buffer list.
785 This affects the operation of @code{other-buffer}. However, if
786 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
789 The @code{switch-to-buffer} function is often used interactively, as
790 the binding of @kbd{C-x b}. It is also used frequently in programs. It
791 always returns @code{nil}.
794 @deffn Command switch-to-buffer-other-window buffer-or-name
795 This function makes @var{buffer-or-name} the current buffer and
796 displays it in a window not currently selected. It then selects that
797 window. The handling of the buffer is the same as in
798 @code{switch-to-buffer}.
800 The currently selected window is absolutely never used to do the job.
801 If it is the only window, then it is split to make a distinct window for
802 this purpose. If the selected window is already displaying the buffer,
803 then it continues to do so, but another window is nonetheless found to
804 display it in as well.
807 @defun pop-to-buffer buffer-or-name &optional other-window on-frame
808 This function makes @var{buffer-or-name} the current buffer and
809 switches to it in some window, preferably not the window previously
810 selected. The ``popped-to'' window becomes the selected window within
813 If the variable @code{pop-up-frames} is non-@code{nil},
814 @code{pop-to-buffer} looks for a window in any visible frame already
815 displaying the buffer; if there is one, it returns that window and makes
816 it be selected within its frame. If there is none, it creates a new
817 frame and displays the buffer in it.
819 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
820 operates entirely within the selected frame. (If the selected frame has
821 just a minibuffer, @code{pop-to-buffer} operates within the most
822 recently selected frame that was not just a minibuffer.)
824 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
825 be split to create a new window that is different from the original
826 window. For details, see @ref{Choosing Window}.
828 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
829 creates another window even if @var{buffer-or-name} is already visible
830 in the selected window. Thus @var{buffer-or-name} could end up
831 displayed in two windows. On the other hand, if @var{buffer-or-name} is
832 already displayed in the selected window and @var{other-window} is
833 @code{nil}, then the selected window is considered sufficient display
834 for @var{buffer-or-name}, so that nothing needs to be done.
836 All the variables that affect @code{display-buffer} affect
837 @code{pop-to-buffer} as well. @xref{Choosing Window}.
839 If @var{buffer-or-name} is a string that does not name an existing
840 buffer, a buffer by that name is created. The major mode for the new
841 buffer is set according to the variable @code{default-major-mode}.
842 @xref{Auto Major Mode}.
844 If @var{on-frame} is non-@code{nil}, it is the frame to pop to this
847 An example use of this function is found at the end of @ref{Filter
851 @deffn Command replace-buffer-in-windows buffer &optional which-frames which-devices
852 This function replaces @var{buffer} with some other buffer in all
853 windows displaying it. The other buffer used is chosen with
854 @code{other-buffer}. In the usual applications of this function, you
855 don't care which other buffer is used; you just want to make sure that
856 @var{buffer} is no longer displayed.
858 The optional arguments @var{which-frames} and @var{which-devices} have
859 the same meaning as with @code{delete-windows-on}.
861 This function returns @code{nil}.
865 @node Choosing Window
866 @section Choosing a Window for Display
868 This section describes the basic facility that chooses a window to
869 display a buffer in---@code{display-buffer}. All the higher-level
870 functions and commands use this subroutine. Here we describe how to use
871 @code{display-buffer} and how to customize it.
873 @deffn Command display-buffer buffer-or-name &optional not-this-window override-frame
874 This command makes @var{buffer-or-name} appear in some window, like
875 @code{pop-to-buffer}, but it does not select that window and does not
876 make the buffer current. The identity of the selected window is
877 unaltered by this function.
879 @var{buffer-or-name} can be a buffer or the name of one.
881 If @var{not-this-window} is non-@code{nil}, it means to display the
882 specified buffer in a window other than the selected one, even if it is
883 already on display in the selected window. This can cause the buffer to
884 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
885 already being displayed in any window, that is good enough, so this
886 function does nothing.
888 If @var{override-frame} is non-@code{nil}, display on that frame instead
889 of the current frame (or the dedicated frame).
891 @code{display-buffer} returns the window chosen to display @var{buffer-or-name}.
893 Precisely how @code{display-buffer} finds or creates a window depends on
894 the variables described below.
898 @cindex dedicated window
899 A window can be marked as ``dedicated'' to a particular buffer.
900 Then SXEmacs will not automatically change which buffer appears in the
901 window, such as @code{display-buffer} might normally do.
903 @defun window-dedicated-p window
904 This function returns @var{window}'s dedicated object, usually @code{t}
908 @defun set-window-buffer-dedicated window buffer
909 This function makes @var{window} display @var{buffer} and be dedicated
910 to that buffer. Then SXEmacs will not automatically change which buffer
911 appears in @var{window}. If @var{buffer} is @code{nil}, this function makes
912 @var{window} not be dedicated (but doesn't change which buffer appears
916 @defopt pop-up-windows
917 This variable controls whether @code{display-buffer} makes new windows.
918 If it is non-@code{nil} and there is only one window, then that window
919 is split. If it is @code{nil}, then @code{display-buffer} does not
920 split the single window, but uses it whole.
923 @defopt split-height-threshold
924 This variable determines when @code{display-buffer} may split a window,
925 if there are multiple windows. @code{display-buffer} always splits the
926 largest window if it has at least this many lines. If the largest
927 window is not this tall, it is split only if it is the sole window and
928 @code{pop-up-windows} is non-@code{nil}.
932 @defopt pop-up-frames
933 This variable controls whether @code{display-buffer} makes new frames.
934 If it is non-@code{nil}, @code{display-buffer} looks for an existing
935 window already displaying the desired buffer, on any visible frame. If
936 it finds one, it returns that window. Otherwise it makes a new frame.
937 The variables @code{pop-up-windows} and @code{split-height-threshold} do
938 not matter if @code{pop-up-frames} is non-@code{nil}.
940 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
941 splits a window or reuses one.
943 @xref{Frames}, for more information.
947 @defvar pop-up-frame-function
948 This variable specifies how to make a new frame if @code{pop-up-frames}
951 Its value should be a function of no arguments. When
952 @code{display-buffer} makes a new frame, it does so by calling that
953 function, which should return a frame. The default value of the
954 variable is a function that creates a frame using properties from
955 @code{pop-up-frame-plist}.
958 @defvar pop-up-frame-plist
959 This variable holds a plist specifying frame properties used when
960 @code{display-buffer} makes a new frame. @xref{Frame Properties}, for
961 more information about frame properties.
964 @defvar special-display-buffer-names
965 A list of buffer names for buffers that should be displayed specially.
966 If the buffer's name is in this list, @code{display-buffer} handles the
969 By default, special display means to give the buffer a dedicated frame.
971 If an element is a list, instead of a string, then the @sc{car} of the
972 list is the buffer name, and the rest of the list says how to create the
973 frame. There are two possibilities for the rest of the list. It can be
974 a plist, specifying frame properties, or it can contain a function and
975 arguments to give to it. (The function's first argument is always the
976 buffer to be displayed; the arguments from the list come after that.)
979 @defvar special-display-regexps
980 A list of regular expressions that specify buffers that should be
981 displayed specially. If the buffer's name matches any of the regular
982 expressions in this list, @code{display-buffer} handles the buffer
985 By default, special display means to give the buffer a dedicated frame.
987 If an element is a list, instead of a string, then the @sc{car} of the
988 list is the regular expression, and the rest of the list says how to
989 create the frame. See above, under @code{special-display-buffer-names}.
992 @defvar special-display-function
993 This variable holds the function to call to display a buffer specially.
994 It receives the buffer as an argument, and should return the window in
995 which it is displayed.
997 The default value of this variable is
998 @code{special-display-popup-frame}.
1001 @defun special-display-popup-frame buffer
1002 This function makes @var{buffer} visible in a frame of its own. If
1003 @var{buffer} is already displayed in a window in some frame, it makes
1004 the frame visible and raises it, to use that window. Otherwise, it
1005 creates a frame that will be dedicated to @var{buffer}.
1007 This function uses an existing window displaying @var{buffer} whether or
1008 not it is in a frame of its own; but if you set up the above variables
1009 in your init file, before @var{buffer} was created, then presumably the
1010 window was previously made by this function.
1013 @defopt special-display-frame-plist
1014 This variable holds frame properties for
1015 @code{special-display-popup-frame} to use when it creates a frame.
1018 @defvar same-window-buffer-names
1019 A list of buffer names for buffers that should be displayed in the
1020 selected window. If the buffer's name is in this list,
1021 @code{display-buffer} handles the buffer by switching to it in the
1025 @defvar same-window-regexps
1026 A list of regular expressions that specify buffers that should be
1027 displayed in the selected window. If the buffer's name matches any of
1028 the regular expressions in this list, @code{display-buffer} handles the
1029 buffer by switching to it in the selected window.
1033 @defvar display-buffer-function
1034 This variable is the most flexible way to customize the behavior of
1035 @code{display-buffer}. If it is non-@code{nil}, it should be a function
1036 that @code{display-buffer} calls to do the work. The function should
1037 accept two arguments, the same two arguments that @code{display-buffer}
1038 received. It should choose or create a window, display the specified
1039 buffer, and then return the window.
1041 This hook takes precedence over all the other options and hooks
1046 @cindex dedicated window
1047 A window can be marked as ``dedicated'' to its buffer. Then
1048 @code{display-buffer} does not try to use that window.
1050 @defun window-dedicated-p window
1051 This function returns @code{t} if @var{window} is marked as dedicated;
1052 otherwise @code{nil}.
1055 @defun set-window-dedicated-p window flag
1056 This function marks @var{window} as dedicated if @var{flag} is
1057 non-@code{nil}, and nondedicated otherwise.
1062 @section Windows and Point
1063 @cindex window position
1064 @cindex window point
1065 @cindex position in window
1066 @cindex point in window
1068 Each window has its own value of point, independent of the value of
1069 point in other windows displaying the same buffer. This makes it useful
1070 to have multiple windows showing one buffer.
1074 The window point is established when a window is first created; it is
1075 initialized from the buffer's point, or from the window point of another
1076 window opened on the buffer if such a window exists.
1079 Selecting a window sets the value of point in its buffer to the window's
1080 value of point. Conversely, deselecting a window sets the window's
1081 value of point from that of the buffer. Thus, when you switch between
1082 windows that display a given buffer, the point value for the selected
1083 window is in effect in the buffer, while the point values for the other
1084 windows are stored in those windows.
1087 As long as the selected window displays the current buffer, the window's
1088 point and the buffer's point always move together; they remain equal.
1091 @xref{Positions}, for more details on buffer positions.
1094 As far as the user is concerned, point is where the cursor is, and
1095 when the user switches to another buffer, the cursor jumps to the
1096 position of point in that buffer.
1098 @defun window-point &optional window
1099 This function returns the current position of point in @var{window}.
1100 For a non-selected window, this is the value point would have (in that
1101 window's buffer) if that window were selected.
1103 When @var{window} is the selected window and its buffer is also the
1104 current buffer, the value returned is the same as the value of point in
1107 Strictly speaking, it would be more correct to return the
1108 ``top-level'' value of point, outside of any @code{save-excursion}
1109 forms. But that value is hard to find.
1112 @defun set-window-point window position
1113 This function positions point in @var{window} at position
1114 @var{position} in @var{window}'s buffer.
1119 @section The Window Start Position
1121 Each window contains a marker used to keep track of a buffer position
1122 that specifies where in the buffer display should start. This position
1123 is called the @dfn{display-start} position of the window (or just the
1124 @dfn{start}). The character after this position is the one that appears
1125 at the upper left corner of the window. It is usually, but not
1126 inevitably, at the beginning of a text line.
1128 @defun window-start &optional window
1129 @cindex window top line
1130 This function returns the display-start position of window
1131 @var{window}. If @var{window} is @code{nil}, the selected window is
1141 When you create a window, or display a different buffer in it, the
1142 display-start position is set to a display-start position recently used
1143 for the same buffer, or 1 if the buffer doesn't have any.
1145 For a realistic example, see the description of @code{count-lines} in
1149 @defun window-end &optional window guarantee
1150 This function returns the position of the end of the display in window
1151 @var{window}. If @var{window} is @code{nil}, the selected window is
1154 Simply changing the buffer text or setting @code{window-start} does not
1155 update the value that @code{window-end} returns. The value is updated
1156 only when SXEmacs redisplays and redisplay actually finishes.
1158 If the last redisplay of @var{window} was preempted, and did not finish,
1159 SXEmacs does not know the position of the end of display in that window.
1160 In that case, this function returns a value that is not correct. In a
1161 future version, @code{window-end} will return @code{nil} in that case.
1163 If optional arg @var{guarantee} is non-@code{nil}, the return value is
1164 guaranteed to be the same as @code{window-end} would return at the end
1165 of the next full redisplay assuming nothing else changes in the
1166 meantime. This function is potentially much slower with this flag set.
1169 in that case, this function returns @code{nil}. You can compute where
1170 the end of the window @emph{would} have been, if redisplay had finished,
1175 (goto-char (window-start window))
1176 (vertical-motion (1- (window-height window))
1183 @defun set-window-start window position &optional noforce
1184 This function sets the display-start position of @var{window} to
1185 @var{position} in @var{window}'s buffer. It returns @var{position}.
1187 The display routines insist that the position of point be visible when a
1188 buffer is displayed. Normally, they change the display-start position
1189 (that is, scroll the window) whenever necessary to make point visible.
1190 However, if you specify the start position with this function using
1191 @code{nil} for @var{noforce}, it means you want display to start at
1192 @var{position} even if that would put the location of point off the
1193 screen. If this does place point off screen, the display routines move
1194 point to the left margin on the middle line in the window.
1196 For example, if point @w{is 1} and you set the start of the window @w{to
1197 2}, then point would be ``above'' the top of the window. The display
1198 routines will automatically move point if it is still 1 when redisplay
1199 occurs. Here is an example:
1203 ;; @r{Here is what @samp{foo} looks like before executing}
1204 ;; @r{the @code{set-window-start} expression.}
1208 ---------- Buffer: foo ----------
1209 @point{}This is the contents of buffer foo.
1215 ---------- Buffer: foo ----------
1221 (1+ (window-start)))
1226 ;; @r{Here is what @samp{foo} looks like after executing}
1227 ;; @r{the @code{set-window-start} expression.}
1228 ---------- Buffer: foo ----------
1229 his is the contents of buffer foo.
1235 ---------- Buffer: foo ----------
1239 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1240 off screen at the next redisplay, then redisplay computes a new window-start
1241 position that works well with point, and thus @var{position} is not used.
1244 @defun pos-visible-in-window-p &optional position window
1245 This function returns @code{t} if @var{position} is within the range
1246 of text currently visible on the screen in @var{window}. It returns
1247 @code{nil} if @var{position} is scrolled vertically out of view. The
1248 argument @var{position} defaults to the current position of point;
1249 @var{window}, to the selected window. Here is an example:
1253 (or (pos-visible-in-window-p
1254 (point) (selected-window))
1259 The @code{pos-visible-in-window-p} function considers only vertical
1260 scrolling. If @var{position} is out of view only because @var{window}
1261 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
1262 @code{t}. @xref{Horizontal Scrolling}.
1266 @node Vertical Scrolling
1267 @section Vertical Scrolling
1268 @cindex vertical scrolling
1269 @cindex scrolling vertically
1271 Vertical scrolling means moving the text up or down in a window. It
1272 works by changing the value of the window's display-start location. It
1273 may also change the value of @code{window-point} to keep it on the
1276 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1277 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1278 you are looking through the window. Imagine that the text is
1279 written on a long roll of paper and that the scrolling commands move the
1280 paper up and down. Thus, if you are looking at text in the middle of a
1281 buffer and repeatedly call @code{scroll-down}, you will eventually see
1282 the beginning of the buffer.
1284 Some people have urged that the opposite convention be used: they
1285 imagine that the window moves over text that remains in place. Then
1286 ``down'' commands would take you to the end of the buffer. This view is
1287 more consistent with the actual relationship between windows and the
1288 text in the buffer, but it is less like what the user sees. The
1289 position of a window on the terminal does not move, and short scrolling
1290 commands clearly move the text up or down on the screen. We have chosen
1291 names that fit the user's point of view.
1293 The scrolling functions (aside from @code{scroll-other-window}) have
1294 unpredictable results if the current buffer is different from the buffer
1295 that is displayed in the selected window. @xref{Current Buffer}.
1297 @deffn Command scroll-up &optional lines
1298 This function scrolls the text in the selected window upward
1299 @var{lines} lines. If @var{lines} is negative, scrolling is actually
1302 If @var{lines} is @code{nil} (or omitted), then the length of scroll
1303 is @code{next-screen-context-lines} lines less than the usable height of
1304 the window (not counting its modeline).
1306 @code{scroll-up} returns @code{nil}.
1309 @deffn Command scroll-down &optional lines
1310 This function scrolls the text in the selected window downward
1311 @var{lines} lines. If @var{lines} is negative, scrolling is actually
1314 If @var{lines} 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
1316 the window (not counting its mode line).
1318 @code{scroll-down} returns @code{nil}.
1321 @deffn Command scroll-other-window &optional lines
1322 This function scrolls the text in another window upward @var{lines}
1323 lines. Negative values of @var{lines}, or @code{nil}, are handled
1324 as in @code{scroll-up}.
1326 You can specify a buffer to scroll with the variable
1327 @code{other-window-scroll-buffer}. When the selected window is the
1328 minibuffer, the next window is normally the one at the top left corner.
1329 You can specify a different window to scroll with the variable
1330 @code{minibuffer-scroll-window}. This variable has no effect when any
1331 other window is selected. @xref{Minibuffer Misc}.
1333 When the minibuffer is active, it is the next window if the selected
1334 window is the one at the bottom right corner. In this case,
1335 @code{scroll-other-window} attempts to scroll the minibuffer. If the
1336 minibuffer contains just one line, it has nowhere to scroll to, so the
1337 line reappears after the echo area momentarily displays the message
1338 ``Beginning of buffer''.
1342 @defvar other-window-scroll-buffer
1343 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1344 which buffer to scroll.
1348 This variable controls how scrolling is done automatically when point
1349 moves off the screen. If the value is zero, then redisplay scrolls the
1350 text to center point vertically in the window. If the value is a
1351 positive integer @var{n}, then redisplay brings point back on screen by
1352 scrolling @var{n} lines in either direction, if possible; otherwise, it
1353 centers point. The default value is zero.
1356 @defopt scroll-conservatively
1357 This variable controls how many lines SXEmacs tries to scroll before
1358 recentering. If you set it to a small number, then when you move point
1359 a short distance off the screen, SXEmacs will scroll the screen just far
1360 enough to bring point back on screen, provided that does not exceed
1361 @code{scroll-conservatively} lines. This variable overrides the
1362 redisplay preemption.
1365 @defopt next-screen-context-lines
1366 The value of this variable is the number of lines of continuity to
1367 retain when scrolling by full screens. For example, @code{scroll-up}
1368 with an argument of @code{nil} scrolls so that this many lines at the
1369 bottom of the window appear instead at the top. The default value is
1373 @deffn Command recenter &optional location window
1374 @cindex centering point
1375 This function scrolls @var{window} (which defaults to the selected
1376 window) to put the text where point is located at a specified vertical
1377 position within the window.
1379 If @var{location} is a nonnegative number, it puts the line containing
1380 point @var{location} lines down from the top of the window. If @var{location}
1381 is a negative number, then it counts upward from the bottom of the
1382 window, so that @minus{}1 stands for the last usable line in the window.
1383 If @var{location} is a non-@code{nil} list, then it stands for the line in
1384 the middle of the window.
1386 If @var{location} is @code{nil}, @code{recenter} puts the line containing
1387 point in the middle of the window, then clears and redisplays the entire
1390 When @code{recenter} is called interactively, @var{location} is the raw
1391 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1392 @var{location} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1393 @var{location} to 4, which positions the current line four lines from the
1396 With an argument of zero, @code{recenter} positions the current line at
1397 the top of the window. This action is so handy that some people make a
1398 separate key binding to do this. For example,
1402 (defun line-to-top-of-window ()
1403 "Scroll current line to top of window.
1404 Replaces three keystroke sequence C-u 0 C-l."
1408 (global-set-key [kp-multiply] 'line-to-top-of-window)
1414 @node Horizontal Scrolling
1415 @section Horizontal Scrolling
1416 @cindex horizontal scrolling
1418 Because we read English first from top to bottom and second from left
1419 to right, horizontal scrolling is not like vertical scrolling. Vertical
1420 scrolling involves selection of a contiguous portion of text to display.
1421 Horizontal scrolling causes part of each line to go off screen. The
1422 amount of horizontal scrolling is therefore specified as a number of
1423 columns rather than as a position in the buffer. It has nothing to do
1424 with the display-start position returned by @code{window-start}.
1426 Usually, no horizontal scrolling is in effect; then the leftmost
1427 column is at the left edge of the window. In this state, scrolling to
1428 the right is meaningless, since there is no data to the left of the
1429 screen to be revealed by it; so this is not allowed. Scrolling to the
1430 left is allowed; it scrolls the first columns of text off the edge of
1431 the window and can reveal additional columns on the right that were
1432 truncated before. Once a window has a nonzero amount of leftward
1433 horizontal scrolling, you can scroll it back to the right, but only so
1434 far as to reduce the net horizontal scroll to zero. There is no limit
1435 to how far left you can scroll, but eventually all the text will
1436 disappear off the left edge.
1438 @deffn Command scroll-left &optional count
1439 This function scrolls the selected window @var{count} columns to the
1440 left (or to the right if @var{count} is negative). The return value is
1441 the total amount of leftward horizontal scrolling in effect after the
1442 change---just like the value returned by @code{window-hscroll} (below).
1445 @deffn Command scroll-right &optional count
1446 This function scrolls the selected window @var{count} columns to the
1447 right (or to the left if @var{count} is negative). The return value is
1448 the total amount of leftward horizontal scrolling in effect after the
1449 change---just like the value returned by @code{window-hscroll} (below).
1451 Once you scroll a window as far right as it can go, back to its normal
1452 position where the total leftward scrolling is zero, attempts to scroll
1453 any farther right have no effect.
1456 @defun window-hscroll &optional window
1457 This function returns the total leftward horizontal scrolling of
1458 @var{window}---the number of columns by which the text in @var{window}
1459 is scrolled left past the left margin.
1461 The value is never negative. It is zero when no horizontal scrolling
1462 has been done in @var{window} (which is usually the case).
1464 If @var{window} is @code{nil}, the selected window is used.
1482 @defun set-window-hscroll window columns
1483 This function sets the number of columns from the left margin that
1484 @var{window} is scrolled to the value of @var{columns}. The argument
1485 @var{columns} should be zero or positive; if not, it is taken as zero.
1487 The value returned is @var{columns}.
1491 (set-window-hscroll (selected-window) 10)
1497 Here is how you can determine whether a given position @var{position}
1498 is off the screen due to horizontal scrolling:
1502 (defun hscroll-on-screen (window position)
1504 (goto-char position)
1506 (>= (- (current-column) (window-hscroll window)) 0)
1507 (< (- (current-column) (window-hscroll window))
1508 (window-width window)))))
1513 @node Size of Window
1514 @section The Size of a Window
1516 @cindex size of window
1518 A SXEmacs window is rectangular, and its size information consists of
1519 the height (in lines or pixels) and the width (in character positions
1520 or pixels). The modeline is included in the height. The pixel
1521 width and height values include scrollbars and margins, while the
1522 line/character-position values do not.
1524 Note that the height in lines, and the width in characters, are
1525 determined by dividing the corresponding pixel value by the height or
1526 width of the default font in that window (if this is a variable-width
1527 font, the average width is used). The resulting values may or may not
1528 represent the actual number of lines in the window, or the actual number
1529 of character positions in any particular line, esp. if there are pixmaps
1530 or various different fonts in the window.
1532 The following functions return size information about a window:
1534 @defun window-height &optional window
1535 This function returns the number of lines in @var{window}, including
1536 its modeline but not including the horizontal scrollbar, if any (this
1537 is different from @code{window-pixel-height}). If @var{window} is
1538 @code{nil}, the function uses the selected window.
1546 (split-window-vertically)
1547 @result{} #<window on "windows.texi" 0x679b>
1556 @defun window-width &optional window
1557 This function returns the number of columns in @var{window}, not
1558 including any left margin, right margin, or vertical scrollbar (this is
1559 different from @code{window-pixel-width}). If @var{window} is
1560 @code{nil}, the function uses the selected window.
1572 (split-window-horizontally)
1573 @result{} #<window on "windows.texi" 0x7538>
1582 Note that after splitting the window into two side-by-side windows,
1583 the width of each window is less the half the width of the original
1584 window because a vertical scrollbar appeared between the windows,
1585 occupying two columns worth of space. Also, the height shrunk by
1586 one because horizontal scrollbars appeared that weren't there
1587 before. (Horizontal scrollbars appear only when lines are
1588 truncated, not when they wrap. This is usually the case for
1589 horizontally split windows but not for full-frame windows. You
1590 can change this using the variables @code{truncate-lines} and
1591 @code{truncate-partial-width-windows}.)
1593 @defun window-pixel-height &optional window
1594 This function returns the height of @var{window} in pixels, including
1595 its modeline and horizontal scrollbar, if any. If @var{window} is
1596 @code{nil}, the function uses the selected window.
1600 (window-pixel-height)
1604 (split-window-vertically)
1605 @result{} #<window on "windows.texi" 0x68a6>
1608 (window-pixel-height)
1614 @defun window-pixel-width &optional window
1615 This function returns the width of @var{window} in pixels, including
1616 any left margin, right margin, or vertical scrollbar that may be
1617 displayed alongside it. If @var{window} is @code{nil}, the function
1618 uses the selected window.
1622 (window-pixel-width)
1626 (window-pixel-height)
1630 (split-window-horizontally)
1631 @result{} #<window on "windows.texi" 0x7538>
1634 (window-pixel-width)
1638 (window-pixel-height)
1644 @defun window-text-area-pixel-height &optional window
1645 This function returns the height in pixels of the text displaying
1646 portion of @var{window}, which defaults to the selected window. Unlike
1647 @code{window-pixel-height}, the space occupied by the modeline and
1648 horizontal scrollbar, if any, is not counted.
1651 @defun window-text-area-pixel-width &optional window
1652 This function returns the width in pixels of the text displaying
1653 portion of @var{window}, which defaults to the selected window. Unlike
1654 @code{window-pixel-width}, the space occupied by the vertical scrollbar
1655 and divider, if any, is not counted.
1658 @defun window-displayed-text-pixel-height &optional window noclipped
1659 This function returns the height in pixels of the text displayed in
1660 @var{window}, which defaults to the selected window. Unlike
1661 @code{window-text-area-pixel-height}, any blank space below the
1662 end of the buffer is not included. If optional argument @var{noclipped}
1663 is non-@code{nil}, any space occupied by clipped lines will not be
1668 @node Position of Window
1669 @section The Position of a Window
1670 @cindex window position
1671 @cindex position of window
1673 SXEmacs provides functions to determine the absolute location of windows
1674 within a frame, and the relative location of a window in comparison to
1675 other windows in the same frame.
1677 @defun window-pixel-edges &optional window
1678 This function returns a list of the pixel edge coordinates of
1679 @var{window}. If @var{window} is @code{nil}, the selected window is
1682 The order of the list is @code{(@var{left} @var{top} @var{right}
1683 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1684 @var{window}'s frame. The element @var{right} of the value is one more
1685 than the rightmost pixel used by @var{window} (including any left
1686 margin, right margin, or vertical scrollbar displayed alongside it), and
1687 @var{bottom} is one more than the bottommost pixel used by @var{window}
1688 (including any modeline or horizontal scrollbar displayed above or below
1689 it). The frame area does not include any frame menubars, toolbars, or
1690 gutters that may be displayed; thus, for example, if there is only one
1691 window on the frame, the values for @var{left} and @var{top} will always
1694 If @var{window} is at the upper left corner of its frame, @var{right}
1695 and @var{bottom} are the same as the values returned by
1696 @code{(window-pixel-width)} and @code{(window-pixel-height)}
1697 respectively, and @var{left} and @var{top} are zero.
1700 There is no longer a function @code{window-edges} because it does not
1701 make sense in a world with variable-width and variable-height lines,
1702 as are allowed in SXEmacs.
1704 @defun window-highest-p window
1705 This function returns non-@code{nil} if @var{window} is along the
1709 @defun window-lowest-p window
1710 This function returns non-@code{nil} if @var{window} is along the
1711 bottom of its frame.
1714 @defun window-text-area-pixel-edges &optional window
1715 This function allows one to determine the location of the
1716 text-displaying portion of @var{window}, which defaults to the selected
1717 window, with respect to the top left corner of the window. It returns
1718 a list of integer pixel positions @code{(left top right bottom)}, all
1719 relative to @code{(0,0)} at the top left corner of the window.
1723 @node Resizing Windows
1724 @section Changing the Size of a Window
1725 @cindex window resizing
1726 @cindex changing window size
1727 @cindex window size, changing
1729 The window size functions fall into two classes: high-level commands
1730 that change the size of windows and low-level functions that access
1731 window size. SXEmacs does not permit overlapping windows or gaps between
1732 windows, so resizing one window affects other windows.
1734 @deffn Command enlarge-window count &optional horizontal window
1735 This function makes the selected window @var{count} lines taller,
1736 stealing lines from neighboring windows. It takes the lines from one
1737 window at a time until that window is used up, then takes from another.
1738 If a window from which lines are stolen shrinks below
1739 @code{window-min-height} lines, that window disappears.
1741 If @var{horizontal} is non-@code{nil}, this function makes
1742 @var{window} wider by @var{count} columns, stealing columns instead of
1743 lines. If a window from which columns are stolen shrinks below
1744 @code{window-min-width} columns, that window disappears.
1746 If the requested size would exceed that of the window's frame, then the
1747 function makes the window occupy the entire height (or width) of the
1750 If @var{count} is negative, this function shrinks the window by
1751 @minus{}@var{count} lines or columns. If that makes the window smaller
1752 than the minimum size (@code{window-min-height} and
1753 @code{window-min-width}), @code{enlarge-window} deletes the window.
1755 If @var{window} is non-@code{nil}, it specifies a window to change
1756 instead of the selected window.
1758 @code{enlarge-window} returns @code{nil}.
1761 @deffn Command enlarge-window-horizontally columns
1762 This function makes the selected window @var{columns} wider.
1763 It could be defined as follows:
1767 (defun enlarge-window-horizontally (columns)
1768 (enlarge-window columns t))
1773 @deffn Command enlarge-window-pixels count &optional side window
1774 This function makes the selected window @var{count} pixels larger.
1775 When called from Lisp, optional second argument @var{side}
1776 non-@code{nil} means to grow sideways @var{count} pixels, and optional
1777 third argument @var{window} specifies the window to change instead of
1778 the selected window.
1781 @deffn Command shrink-window count &optional horizontal window
1782 This function is like @code{enlarge-window} but negates the argument
1783 @var{count}, making the selected window smaller by giving lines (or
1784 columns) to the other windows. If the window shrinks below
1785 @code{window-min-height} or @code{window-min-width}, then it disappears.
1787 If @var{count} is negative, the window is enlarged by @minus{}@var{count}
1790 If @var{window} is non-@code{nil}, it specifies a window to change
1791 instead of the selected window.
1794 @deffn Command shrink-window-horizontally columns
1795 This function makes the selected window @var{columns} narrower.
1796 It could be defined as follows:
1800 (defun shrink-window-horizontally (columns)
1801 (shrink-window columns t))
1806 @deffn Command shrink-window-pixels count &optional side window
1807 This function makes the selected window @var{count} pixels smaller.
1808 When called from Lisp, optional second argument @var{side}
1809 non-@code{nil} means to shrink sideways @var{count} pixels, and optional
1810 third argument @var{window} specifies the window to change instead of
1811 the selected window.
1814 @cindex minimum window size
1815 The following two variables constrain the window-size-changing
1816 functions to a minimum height and width.
1818 @defopt window-min-height
1819 The value of this variable determines how short a window may become
1820 before it is automatically deleted. Making a window smaller than
1821 @code{window-min-height} automatically deletes it, and no window may be
1822 created shorter than this. The absolute minimum height is two (allowing
1823 one line for the mode line, and one line for the buffer display).
1824 Actions that change window sizes reset this variable to two if it is
1825 less than two. The default value is 4.
1828 @defopt window-min-width
1829 The value of this variable determines how narrow a window may become
1830 before it automatically deleted. Making a window smaller than
1831 @code{window-min-width} automatically deletes it, and no window may be
1832 created narrower than this. The absolute minimum width is one; any
1833 value below that is ignored. The default value is 10.
1836 @c This is not yet implemented. Why is it "documented"?
1837 @defvar window-size-change-functions
1838 This variable holds a list of functions to be called if the size of any
1839 window changes for any reason. The functions are called just once per
1840 redisplay, and just once for each frame on which size changes have
1843 Each function receives the frame as its sole argument. There is no
1844 direct way to find out which windows changed size, or precisely how;
1845 however, if your size-change function keeps track, after each change, of
1846 the windows that interest you, you can figure out what has changed by
1847 comparing the old size data with the new.
1849 Creating or deleting windows counts as a size change, and therefore
1850 causes these functions to be called. Changing the frame size also
1851 counts, because it changes the sizes of the existing windows.
1853 It is not a good idea to use @code{save-window-excursion} in these
1854 functions, because that always counts as a size change, and it would
1855 cause these functions to be called over and over. In most cases,
1856 @code{save-selected-window} is what you need here.
1860 @node Window Configurations
1861 @section Window Configurations
1862 @cindex window configurations
1863 @cindex saving window information
1865 A @dfn{window configuration} records the entire layout of a
1866 frame---all windows, their sizes, which buffers they contain, what part
1867 of each buffer is displayed, and the values of point and the mark. You
1868 can bring back an entire previous layout by restoring a window
1869 configuration previously saved.
1871 If you want to record all frames instead of just one, use a frame
1872 configuration instead of a window configuration. @xref{Frame
1875 Use the window configuration hook whenever you need to dynamicly
1876 adapt to window configuration changes. @xref{Window Configuration
1879 @defun current-window-configuration &optional frame
1880 This function returns a new object representing the current window
1881 configuration of @var{frame}, namely the number of windows, their sizes
1882 and current buffers, which window is the selected window, and for each
1883 window the displayed buffer, the display-start position, and the
1884 positions of point and the mark. An exception is made for point in the
1885 current buffer, whose value is not saved.
1887 @var{frame} defaults to the selected frame.
1890 @defun set-window-configuration configuration
1891 This function restores the configuration of SXEmacs's windows and
1892 buffers to the state specified by @var{configuration}. The argument
1893 @var{configuration} must be a value that was previously returned by
1894 @code{current-window-configuration}.
1896 This function always counts as a window size change and triggers
1897 execution of the @code{window-size-change-functions}. (It doesn't know
1898 how to tell whether the new configuration actually differs from the old
1901 Here is a way of using this function to get the same effect
1902 as @code{save-window-excursion}:
1906 (let ((config (current-window-configuration)))
1908 (progn (split-window-vertically nil)
1910 (set-window-configuration config)))
1915 @defspec save-window-excursion forms@dots{}
1916 This special form records the window configuration, executes @var{forms}
1917 in sequence, then restores the earlier window configuration. The window
1918 configuration includes the value of point and the portion of the buffer
1919 that is visible. It also includes the choice of selected window.
1920 However, it does not include the value of point in the current buffer;
1921 use @code{save-excursion} if you wish to preserve that.
1923 Don't use this construct when @code{save-selected-window} is all you need.
1925 Exit from @code{save-window-excursion} always triggers execution of the
1926 @code{window-size-change-functions}. (It doesn't know how to tell
1927 whether the restored configuration actually differs from the one in
1928 effect at the end of the @var{forms}.)
1930 The return value is the value of the final form in @var{forms}.
1936 @result{} #<window 25 on control.texi>
1939 (setq w (selected-window))
1940 @result{} #<window 19 on control.texi>
1943 (save-window-excursion
1944 (delete-other-windows w)
1945 (switch-to-buffer "foo")
1947 @result{} do-something
1948 ;; @r{The frame is now split again.}
1953 @defun window-configuration-p object
1954 This function returns @code{t} if @var{object} is a window configuration.
1957 Primitives to look inside of window configurations would make sense,
1958 but none are implemented. It is not clear they are useful enough to be
1962 @node Window Configuration Hook
1963 @section Window Configuration Hook
1964 @cindex window configuration hook
1966 The @var{window-configuration-hook}, is a list of functions run whenever
1967 the window configuration of a frame changes; such as when a window is
1968 deleted, split or resized.
1970 Each function is called with a window as argument, which window depends
1971 on what function runs the hook.
1973 When a new frame is created, this hook is not run on the newly created
1974 window, please use the @var{create-frame-hook} instead, where each
1975 function recieves the frame as argument.
1977 There is no guarantee that this will only be run at the end of some
1978 function that changes the window configuration (read layout), in fact it
1979 can be run several times while the window layout changes.
1981 The core functions that run this hook try to ensure that it does not
1982 cause infinite loops, but if you run some functions that change the
1983 layout @strong{expect trouble}.
1985 Here is a complete list of core functions, running the hook. All other
1986 window manipulating functions call these and therefore run the hook at
1987 some point in time. If not, that's a bug, and you should report it as
1992 @item @code{delete-window} @xref{Deleting Windows}.
1993 The window that takes the space of the deleted window is recieved as the
1994 argument. If this command deletes the frame, the hook is not run.
1995 @item @code{delete-other-windows} @xref{Deleting Windows}.
1996 The window that is left behind is recieved as argument.
1997 @c buffers and windows
1998 @item @code{set-window-buffer} @xref{Buffers and Windows}.
1999 The window recievied as argument is passed on to the hook.
2000 @c splitting windows
2001 @item @code{split-window} @xref{Splitting Windows}.
2002 The window recievied as argument is passed on to the hook.
2004 @item @code{enlarge-window} @xref{Resizing Windows}.
2005 The window recievied as argument is passed on to the hook.
2006 @item @code{enlarge-window-pixels} @xref{Resizing Windows}.
2007 The window recievied as argument is passed on to the hook..
2008 @item @code{shrink-window} @xref{Resizing Windows}.
2009 The window recievied as argument is passed on to the hook.
2010 @item @code{shrink-window-pixels} @xref{Resizing Windows}.
2011 The window recievied as argument is passed on to the hook.