annotate doc/lispref/windows.texi @ 110211:6cdcc53703e4

mail-source.el (mail-source-fetch): Don't message if we're fetching mail from a file, and the file doesn't exist.
author Katsumi Yamaoka <yamaoka@jpl.org>
date Sun, 05 Sep 2010 23:38:33 +0000
parents 71353caf35e3
children 376148b31b5e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 105542
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
105542
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
5 @c Free Software Foundation, Inc.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84112
diff changeset
7 @setfilename ../../info/windows
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @node Windows, Frames, Buffers, Top
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @chapter Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 This chapter describes most of the functions and variables related to
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
12 Emacs windows. @xref{Frames and Windows}, for how windows relate to
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
13 frames. @xref{Display}, for information on how text is displayed in
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
14 windows.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16 @menu
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 * Basic Windows:: Basic information on using windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 * Splitting Windows:: Splitting one window into two windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 * Deleting Windows:: Deleting a window gives its space to other windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 * Selecting Windows:: The selected window is the one that you edit in.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 * Cyclic Window Ordering:: Moving around the existing windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 * Buffers and Windows:: Each window displays the contents of a buffer.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23 * Displaying Buffers:: Higher-level functions for displaying a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 and choosing a window for it.
109267
71353caf35e3 Untabify doc/lispref/*.texi.
Glenn Morris <rgm@gnu.org>
parents: 108366
diff changeset
25 * Choosing Window:: How to choose a window for displaying a buffer.
71353caf35e3 Untabify doc/lispref/*.texi.
Glenn Morris <rgm@gnu.org>
parents: 108366
diff changeset
26 * Dedicated Windows:: How to avoid displaying another buffer in
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
27 a specific window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 * Window Point:: Each window has its own location of point.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
29 * Window Start and End:: Buffer positions indicating which text is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
30 on-screen in a window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 * Textual Scrolling:: Moving text up and down through the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 * Vertical Scrolling:: Moving the contents up and down on the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33 * Horizontal Scrolling:: Moving the contents sideways on the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 * Size of Window:: Accessing the size of a window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 * Resizing Windows:: Changing the size of a window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 * Coordinates and Windows:: Converting coordinates to windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 * Window Tree:: The layout and sizes of all windows in a frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38 * Window Configurations:: Saving and restoring the state of the screen.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
39 * Window Parameters:: Associating additional information with windows.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40 * Window Hooks:: Hooks for scrolling, window size changes,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 redisplay going past a certain point,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 or window configuration changes.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 @end menu
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 @node Basic Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46 @section Basic Concepts of Emacs Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 @cindex window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 @cindex selected window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 A @dfn{window} in Emacs is the physical area of the screen in which a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51 buffer is displayed. The term is also used to refer to a Lisp object that
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 represents that screen area in Emacs Lisp. It should be
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 clear from the context which is meant.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
55 Emacs groups windows into frames; see @ref{Frames}. A frame
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
56 represents an area of screen available for Emacs to use. Each frame
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
57 always contains at least one window, but you can subdivide it
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
58 vertically or horizontally into multiple, nonoverlapping Emacs
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
59 windows.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 In each frame, at any time, one and only one window is designated as
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 @dfn{selected within the frame}. The frame's cursor appears in that
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 window, but the other windows have ``non-selected'' cursors, normally
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
64 less visible. (@xref{Cursor Parameters}, for customizing this.) At
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
65 any time, one frame is the selected frame; and the window selected
85114
5039706521c9 Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 84116
diff changeset
66 within that frame is @dfn{the selected window}. The selected window's
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
67 buffer is usually the current buffer (except when @code{set-buffer} has
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
68 been used); see @ref{Current Buffer}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 For practical purposes, a window exists only while it is displayed in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 a frame. Once removed from the frame, the window is effectively deleted
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 and should not be used, @emph{even though there may still be references
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
73 to it} from other Lisp objects; see @ref{Deleting Windows}. Restoring a
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
74 saved window configuration is the only way for a window no longer on the
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
75 screen to come back to life; see @ref{Window Configurations}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 @cindex multiple windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 Users create multiple windows so they can look at several buffers at
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 once. Lisp libraries use multiple windows for a variety of reasons, but
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 most often to display related information. In Rmail, for example, you
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81 can move through a summary buffer in one window while the other window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 shows messages one at a time as they are reached.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 The meaning of ``window'' in Emacs is similar to what it means in the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 context of general-purpose window systems such as X, but not identical.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 The X Window System places X windows on the screen; Emacs uses one or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87 more X windows as frames, and subdivides them into
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 Emacs windows. When you use Emacs on a character-only terminal, Emacs
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 treats the whole terminal screen as one frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 @cindex terminal screen
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92 @cindex screen of terminal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 @cindex tiled windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 Most window systems support arbitrarily located overlapping windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 together they fill the whole screen or frame. Because of the way in
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
97 which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
98 them (@pxref{Resizing Windows}), not all conceivable tilings of windows
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
99 on an Emacs frame are actually possible.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 @defun windowp object
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 This function returns @code{t} if @var{object} is a window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @node Splitting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 @section Splitting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 @cindex splitting windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 @cindex window splitting
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
110 The functions described below are the primitives used to split a window
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
111 into two windows. They do not accept a buffer as an argument. Rather,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
112 the two ``halves'' of the split window initially display the same buffer
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 previously visible in the window that was split.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 @deffn Command split-window &optional window size horizontal
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
116 This function splits a new window out of @var{window}'s screen area. It
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
117 returns the new window. The default for @var{window} is the selected
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
118 window. When you split the selected window, it remains selected.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
119
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
120 If @var{horizontal} is non-@code{nil}, then @var{window} splits into two
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
121 side by side windows. The original window keeps the leftmost @var{size}
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
122 columns, and gives the rest of the columns to the new window.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
123 Otherwise, @var{window} splits into windows one above the other, the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
124 original window keeps the upper @var{size} lines and gives the rest of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
125 the lines to the new window. The original window @var{window} is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
126 therefore the left-hand or upper of the two, and the new window is the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
127 right-hand or lower.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 If @var{size} is omitted or @code{nil}, then @var{window} is divided
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 evenly into two parts. (If there is an odd line, it is allocated to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 the new window.) When @code{split-window} is called interactively,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132 all its arguments are @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 If splitting would result in making a window that is smaller than
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
135 @code{window-min-height} or @code{window-min-width} (@pxref{Resizing
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
136 Windows}), @code{split-window} signals an error and does not split the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
137 window at all.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 The following example starts with one window on a screen that is 50
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 lines high by 80 columns wide; then it splits the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 @smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 (setq w (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 @result{} #<window 8 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 (window-edges) ; @r{Edges in order:}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 ;; @r{Returns window created}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 (setq w2 (split-window w 15))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 @result{} #<window 28 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 (window-edges w2)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157 @result{} (0 15 80 50) ; @r{Bottom window;}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 ; @r{top is line 15}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 (window-edges w)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 @result{} (0 0 80 15) ; @r{Top window}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @end smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 The screen looks like this:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 @smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 __________
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 | | line 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172 | w |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 |__________|
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 | | line 15
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 | w2 |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 |__________|
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 line 50
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 column 0 column 80
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 @end smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 Next, split the top window horizontally:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 @smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 (setq w3 (split-window w 35 t))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 @result{} #<window 32 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 (window-edges w3)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @result{} (35 0 80 15) ; @r{Left edge at column 35}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 (window-edges w)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @result{} (0 0 35 15) ; @r{Right edge at column 35}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 (window-edges w2)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 @end smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 @need 3000
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204 Now the screen looks like this:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206 @smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 column 35
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 __________
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 | | | line 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211 | w | w3 |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 |___|______|
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 | | line 15
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 | w2 |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 |__________|
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 line 50
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 column 0 column 80
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 @end smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 Normally, Emacs indicates the border between two side-by-side windows
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
222 with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
223 display table can specify alternative border characters; see @ref{Display
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
224 Tables}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 @deffn Command split-window-vertically &optional size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 This function splits the selected window into two windows, one above the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 other, leaving the upper of the two windows selected, with @var{size}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 lines. (If @var{size} is negative, then the lower of the two windows
98794
72fc90d94beb (Basic Windows, Splitting Windows): Fix whitespace and reword.
Martin Rudalics <rudalics@gmx.at>
parents: 92148
diff changeset
231 gets @minus{}@var{size} lines and the upper window gets the rest, but
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 the upper window is still the one selected.) However, if
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 @code{split-window-keep-point} (see below) is @code{nil}, then either
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 window can be selected.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 In other respects, this function is similar to @code{split-window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 In particular, the upper window is the original one and the return
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 value is the new, lower window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 @defopt split-window-keep-point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 If this variable is non-@code{nil} (the default), then
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 @code{split-window-vertically} behaves as described above.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 If it is @code{nil}, then @code{split-window-vertically} adjusts point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 in each of the two windows to avoid scrolling. (This is useful on
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 slow terminals.) It selects whichever window contains the screen line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 that point was previously on.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249
98794
72fc90d94beb (Basic Windows, Splitting Windows): Fix whitespace and reword.
Martin Rudalics <rudalics@gmx.at>
parents: 92148
diff changeset
250 This variable affects the behavior of @code{split-window-vertically}
72fc90d94beb (Basic Windows, Splitting Windows): Fix whitespace and reword.
Martin Rudalics <rudalics@gmx.at>
parents: 92148
diff changeset
251 only. It has no effect on the other functions described here.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 @deffn Command split-window-horizontally &optional size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 This function splits the selected window into two windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 side-by-side, leaving the selected window on the left with @var{size}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 columns. If @var{size} is negative, the rightmost window gets
98794
72fc90d94beb (Basic Windows, Splitting Windows): Fix whitespace and reword.
Martin Rudalics <rudalics@gmx.at>
parents: 92148
diff changeset
258 @minus{}@var{size} columns, but the leftmost window still remains
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 selected.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 This function is basically an interface to @code{split-window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 You could define a simplified version of the function like this:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 (defun split-window-horizontally (&optional arg)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 "Split selected window into two windows, side by side..."
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268 (interactive "P")
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 (let ((size (and arg (prefix-numeric-value arg))))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 (and size (< size 0)
98794
72fc90d94beb (Basic Windows, Splitting Windows): Fix whitespace and reword.
Martin Rudalics <rudalics@gmx.at>
parents: 92148
diff changeset
273 (setq size (+ (window-width) size)))
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 (split-window nil size t)))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 @end smallexample
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 @defun one-window-p &optional no-mini all-frames
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 This function returns non-@code{nil} if there is only one window. The
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 argument @var{no-mini}, if non-@code{nil}, means don't count the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282 minibuffer even if it is active; otherwise, the minibuffer window is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 counted when it is active.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 The argument @var{all-frames} specifies which frames to consider. Here
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 are the possible values and their meanings:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 @table @asis
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 @item @code{nil}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 Count the windows in the selected frame, plus the minibuffer used
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 by that frame even if it lies in some other frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 @item @code{t}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294 Count all windows in all existing frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296 @item @code{visible}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 Count all windows in all visible frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 @item 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 Count all windows in all visible or iconified frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 @item anything else
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 Count precisely the windows in the selected frame, and no others.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 @end table
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @node Deleting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 @section Deleting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 @cindex deleting windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311 A window remains visible on its frame unless you @dfn{delete} it by
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 calling certain functions that delete windows. A deleted window cannot
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 appear on the screen, but continues to exist as a Lisp object until
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 there are no references to it. There is no way to cancel the deletion
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 of a window aside from restoring a saved window configuration
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 (@pxref{Window Configurations}). Restoring a window configuration also
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317 deletes any windows that aren't part of that configuration.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
319 When you delete a window, the space it took up is given to one of
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
320 its sibling windows adjacent to it.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 @c Emacs 19 feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323 @defun window-live-p window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 This function returns @code{nil} if @var{window} is deleted, and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 @code{t} otherwise.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327 @strong{Warning:} Erroneous information or fatal errors may result from
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 using a deleted window as if it were live.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 @deffn Command delete-window &optional window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
332 This function removes @var{window} from display and returns @code{nil}.
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
333 The default for @var{window} is the selected window. An error is
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
334 signaled if @var{window} is the only window on its frame.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337 @deffn Command delete-other-windows &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 This function makes @var{window} the only window on its frame, by
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
339 deleting the other windows in that frame. The default for @var{window}
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
340 is the selected window. The return value is @code{nil}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342
99128
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
343 @deffn Command delete-windows-on &optional buffer-or-name frame
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 This function deletes all windows showing @var{buffer-or-name}. If
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
345 there are no windows showing @var{buffer-or-name}, it does nothing. The
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
346 optional argument @var{buffer-or-name} may be a buffer or the name of an
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
347 existing buffer and defaults to the current buffer.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 @code{delete-windows-on} operates frame by frame. If a frame has
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 several windows showing different buffers, then those showing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 @var{buffer-or-name} are removed, and the others expand to fill the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 space. If all windows in some frame are showing @var{buffer-or-name}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 (including the case where there is only one window), then the frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 winds up with a single window showing another buffer chosen with
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
355 @code{other-buffer} (@pxref{The Buffer List}). If, however, the window
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
356 showing @var{buffer-or-name} is dedicated to its buffer
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
357 (@pxref{Dedicated Windows}), and there are other frames left, that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
358 window's frame is deleted.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
360 The optional argument @var{frame} specifies which frames to operate on.
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
361 This function does not use it in quite the same way as the other
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
362 functions which scan all windows; specifically, the values @code{t} and
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
363 @code{nil} have the opposite of their meanings in other functions. Here
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
364 are the full details:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 @itemize @bullet
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 If it is @code{nil}, operate on all frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 If it is @code{t}, operate on the selected frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 If it is @code{visible}, operate on all visible frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 If it is 0, operate on all visible or iconified frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 If it is a frame, operate on that frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 @end itemize
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 This function always returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 @node Selecting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 @section Selecting Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 @cindex selecting a window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 When a window is selected, the buffer in the window becomes the current
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 buffer, and the cursor will appear in it.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389 @defun selected-window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 This function returns the selected window. This is the window in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 which the cursor appears and to which many commands apply.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 @defun select-window window &optional norecord
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 This function makes @var{window} the selected window. The cursor then
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
396 appears in @var{window} (after redisplay). Unless @var{window} was
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
397 already selected, @code{select-window} makes @var{window}'s buffer the
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
398 current buffer. The return value is @var{window}.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
399
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
400 Normally, @var{window}'s selected buffer is moved to the front of the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
401 buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
402 recently selected window. But if @var{norecord} is non-@code{nil}, the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
403 buffer list remains unchanged and @var{window} does not become the most
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
404 recently selected one.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
405
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 (setq w (next-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 (select-window w)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 @result{} #<window 65 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416 @defmac save-selected-window forms@dots{}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417 This macro records the selected frame, as well as the selected window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 of each frame, executes @var{forms} in sequence, then restores the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 earlier selected frame and windows. It also saves and restores the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 current buffer. It returns the value of the last form in @var{forms}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 This macro does not save or restore anything about the sizes,
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
423 arrangement or contents of windows; therefore, if @var{forms} change
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
424 them, the change persists. If the previously selected window of some
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
425 frame is no longer live at the time of exit from @var{forms}, that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
426 frame's selected window is left alone. If the previously selected
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
427 window is no longer live, then whatever window is selected at the end of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
428 @var{forms} remains selected. The current buffer is restored if and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
429 only if it is still live when exiting @var{forms}.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
430
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
431 This macro changes neither the ordering of recently selected windows nor
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
432 the buffer list.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 @end defmac
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 @defmac with-selected-window window forms@dots{}
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
436 This macro selects @var{window}, executes @var{forms} in sequence, then
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
437 restores the previously selected window and current buffer. The ordering
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
438 of recently selected windows and the buffer list remain unchanged unless
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
439 you deliberately change them within @var{forms}, for example, by calling
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
440 @code{select-window} with argument @var{norecord} @code{nil}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 @end defmac
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 @cindex finding windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 The following functions choose one of the windows on the screen,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 offering various criteria for the choice.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447 @defun get-lru-window &optional frame dedicated
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 This function returns the window least recently ``used'' (that is,
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
449 selected) among a set of candidate windows. If any full-width windows
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
450 are present, it only considers these.
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
451
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
452 The selected window is returned if it is the only candidate. A
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
453 minibuffer window is never a candidate. A dedicated window
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
454 (@pxref{Dedicated Windows}) is never a candidate unless the optional
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
455 argument @var{dedicated} is non-@code{nil}.
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
456
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
457 The optional argument @var{frame} specifies which windows are
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
458 considered.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 @itemize @bullet
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 If it is @code{nil}, consider windows on the selected frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 If it is @code{t}, consider windows on all frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 If it is @code{visible}, consider windows on all visible frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 If it is 0, consider windows on all visible or iconified frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 If it is a frame, consider windows on that frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 @end itemize
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 @defun get-largest-window &optional frame dedicated
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 This function returns the window with the largest area (height times
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 width). If there are no side-by-side windows, then this is the window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
477 with the most lines. A minibuffer window is never a candidate. A
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
478 dedicated window (@pxref{Dedicated Windows}) is never a candidate unless
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
479 the optional argument @var{dedicated} is non-@code{nil}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 If there are two candidate windows of the same size, this function
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
482 prefers the one that comes first in the cyclic ordering of windows,
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
483 starting from the selected window (@pxref{Cyclic Window Ordering}).
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
484
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
485 The optional argument @var{frame} specifies which set of windows to
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
486 consider, see @code{get-lru-window} above.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 @cindex window that satisfies a predicate
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 @cindex conditional selection of windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491 @defun get-window-with-predicate predicate &optional minibuf all-frames default
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 This function returns a window satisfying @var{predicate}. It cycles
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493 through all visible windows using @code{walk-windows} (@pxref{Cyclic
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
494 Window Ordering}), calling @var{predicate} on each one of them with that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
495 window as its argument. The function returns the first window for which
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
496 @var{predicate} returns a non-@code{nil} value; if that never happens,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
497 it returns @var{default} (which defaults to @code{nil}).
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 The optional arguments @var{minibuf} and @var{all-frames} specify the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 set of windows to include in the scan. See the description of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @code{next-window} in @ref{Cyclic Window Ordering}, for details.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504 @node Cyclic Window Ordering
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505 @comment node-name, next, previous, up
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 @section Cyclic Ordering of Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507 @cindex cyclic ordering of windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 @cindex ordering of windows, cyclic
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 @cindex window ordering, cyclic
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 When you use the command @kbd{C-x o} (@code{other-window}) to select
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
512 some other window, it moves through the windows on the screen in a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
513 specific order. For any given configuration of windows, this order
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
514 never varies. It is called the @dfn{cyclic ordering of windows}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
516 For a particular frame, this ordering generally goes from top to
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
517 bottom, and from left to right. But it may go down first or go right
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
518 first, depending on the order in which windows were split.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 If the first split was vertical (into windows one above each other),
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521 and then the subwindows were split horizontally, then the ordering is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 left to right in the top of the frame, and then left to right in the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 next lower part of the frame, and so on. If the first split was
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524 horizontal, the ordering is top to bottom in the left part, and so on.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
525 In general, within each set of siblings at any level in the window tree
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
526 (@pxref{Window Tree}), the order is left to right, or top to bottom.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
527
107946
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
528 @defun next-window &optional window minibuf all-frames
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 @cindex minibuffer window, and @code{next-window}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530 This function returns the window following @var{window} in the cyclic
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
531 ordering of windows. This is the window @kbd{C-x o} selects if typed
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
532 when @var{window} is selected. The default for @var{window} is the
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
533 selected window.
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
534
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
535 The value of the optional argument @var{minibuf} specifies whether the
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
536 minibuffer is included in the window order. Normally, when
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
537 @var{minibuf} is @code{nil}, the minibuffer is included only if it is
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
538 currently ``active''; this matches the behavior of @kbd{C-x o}. (The
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
539 minibuffer window is active while the minibuffer is in use; see
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
540 @ref{Minibuffers}.)
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
541
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
542 If @var{minibuf} is @code{t}, the cyclic ordering includes the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
543 minibuffer window even if it is not active. If @var{minibuf} is neither
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
544 @code{t} nor @code{nil}, the minibuffer window is not included even if
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
545 it is active.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
547 The optional argument @var{all-frames} specifies which frames to
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
548 consider. Here are the possible values and their meanings:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 @table @asis
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 @item @code{nil}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552 Consider all the windows in @var{window}'s frame, plus the minibuffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 used by that frame even if it lies in some other frame. If the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 minibuffer counts (as determined by @var{minibuf}), then all windows on
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 all frames that share that minibuffer count too.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 @item @code{t}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 Consider all windows in all existing frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 @item @code{visible}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 Consider all windows in all visible frames. (To get useful results, you
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 must ensure @var{window} is in a visible frame.)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 @item 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 Consider all windows in all visible or iconified frames.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567 @item a frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568 Consider all windows on that frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 @item anything else
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 Consider precisely the windows in @var{window}'s frame, and no others.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 @end table
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574 This example assumes there are two windows, both displaying the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 buffer @samp{windows.texi}:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 (selected-window)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 @result{} #<window 56 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 (next-window (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 @result{} #<window 52 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587 (next-window (next-window (selected-window)))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588 @result{} #<window 56 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 @end example
107946
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
591 @end defun
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
592
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
593 @defun previous-window &optional window minibuf all-frames
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 This function returns the window preceding @var{window} in the cyclic
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 ordering of windows. The other arguments specify which windows to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 include in the cycle, as in @code{next-window}.
107946
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
597 @end defun
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 @deffn Command other-window count &optional all-frames
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
600 This function selects another window in the cyclic ordering of windows.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
601 @var{count} specifies the number of windows to skip in the ordering,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
602 starting with the selected window, before making the selection. If
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
603 @var{count} is a positive number, it skips @var{count} windows forwards.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
604 @var{count} negative means skip @minus{}@var{count} windows backwards.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
605 If @var{count} is zero, it does not skip any window, thus re-selecting
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
606 the selected window. In an interactive call, @var{count} is the numeric
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
607 prefix argument.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
609 The optional argument @var{all-frames} has the same meaning as in
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
611 is always effectively @code{nil}. This function returns @code{nil}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 @c Emacs 19 feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 @defun walk-windows proc &optional minibuf all-frames
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 This function cycles through all windows. It calls the function
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617 @code{proc} once for each window, with the window as its sole
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 argument.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 The optional arguments @var{minibuf} and @var{all-frames} specify the
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
621 set of windows to include in the walk. See @code{next-window}, above,
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 for details.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 @defun window-list &optional frame minibuf window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
626 This function returns a list of all windows on @var{frame}, starting
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
627 with @var{window}. The default for @var{frame} is the selected frame;
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
628 the default for @var{window} is the selected window.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
629
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
630 The value of @var{minibuf} specifies if the minibuffer window shall be
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 included in the result list. If @var{minibuf} is @code{t}, the result
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 always includes the minibuffer window. If @var{minibuf} is @code{nil}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 or omitted, that includes the minibuffer window if it is active. If
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 @var{minibuf} is neither @code{nil} nor @code{t}, the result never
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 includes the minibuffer window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 @node Buffers and Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 @section Buffers and Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 @cindex examining windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 @cindex windows, controlling precisely
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 @cindex buffers, controlled in windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 This section describes low-level functions to examine windows or to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645 display buffers in windows in a precisely controlled fashion.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 @iftex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 See the following section for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648 @end iftex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 @ifnottex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 @xref{Displaying Buffers}, for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 @end ifnottex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652 related functions that find a window to use and specify a buffer for it.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
653 The functions described there are easier to use, but they employ
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
654 heuristics in choosing or creating a window; use the functions described
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
655 here when you need complete control.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657 @defun set-window-buffer window buffer-or-name &optional keep-margins
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 This function makes @var{window} display @var{buffer-or-name} as its
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
659 contents. It returns @code{nil}. The default for @var{window} is the
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
660 selected window. The argument @var{buffer-or-name} must specify a
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
661 buffer or the name of an existing buffer.
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
662
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
663 @code{set-window-buffer} is the fundamental primitive for changing which
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
664 buffer is displayed in a window, and all ways of doing that call this
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
665 function.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 (set-window-buffer (selected-window) "foo")
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 @result{} nil
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
674 Normally, displaying @var{buffer-or-name} in @var{window} resets the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
675 window's position, display margins, fringe widths, and scroll bar
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
676 settings based on the local variables of that buffer.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
677 However, if @var{keep-margins} is non-@code{nil}, display margins and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
678 fringe widths of @var{window} remain unchanged. @xref{Fringes}.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
679
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
680 @code{set-window-buffer} signals an error when @var{window} is
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
681 @dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
682 does not already display @var{buffer-or-name}.
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
683
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
684 Note that this function runs @code{window-scroll-functions} before
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
685 running @code{window-configuration-change-hook}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688 @defvar buffer-display-count
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
689 This buffer-local variable records the number of times a buffer has been
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 displayed in a window. It is incremented each time
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691 @code{set-window-buffer} is called for the buffer.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 @defun window-buffer &optional window
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
695 This function returns the buffer that @var{window} is displaying. The
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
696 default for @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700 (window-buffer)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 @result{} #<buffer windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705
99128
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
706 @defun get-buffer-window &optional buffer-or-name all-frames
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707 This function returns a window currently displaying
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 @var{buffer-or-name}, or @code{nil} if there is none. If there are
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 several such windows, then the function returns the first one in the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 cyclic ordering of windows, starting from the selected window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711 @xref{Cyclic Window Ordering}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
713 The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
714 defaults to the current buffer. The optional argument @var{all-frames}
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
715 specifies which windows to consider:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 @itemize @bullet
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
719 @code{nil} means consider windows on the selected frame.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
720 @item
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
721 @code{t} means consider windows on all existing frames.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
723 @code{visible} means consider windows on all visible frames.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
724 @item
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
725 0 means consider windows on all visible or iconified frames.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
727 A frame means consider windows on that frame only.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 @end itemize
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
729
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
730 Observe that the behavior of @code{get-buffer-window} may differ from
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
731 that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
732 @var{all-frames} equals @code{nil} or any value not listed here.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
733 Perhaps we will change @code{get-buffer-window} in the future to make it
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
734 compatible with the other functions.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736
99128
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
737 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
738 This function returns a list of all windows currently displaying
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
739 @var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
740 or the name of an existing buffer and defaults to the current buffer.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
741
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
742 The two remaining arguments work like the same-named arguments of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
743 @code{next-window}; they are @emph{not} like the optional arguments of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
744 @code{get-buffer-window}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747 @defvar buffer-display-time
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 This variable records the time at which a buffer was last made visible
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749 in a window. It is always local in each buffer; each time
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 @code{set-window-buffer} is called, it sets this variable to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 When a buffer is first created, @code{buffer-display-time} starts out
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 with the value @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 @node Displaying Buffers
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 @section Displaying Buffers in Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 @cindex switching to a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 @cindex displaying a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 In this section we describe convenient functions that choose a window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762 automatically and use it to display a specified buffer. These functions
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 can also split an existing window in certain circumstances. We also
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 describe variables that parameterize the heuristics used for choosing a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 @iftex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 See the preceding section for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768 @end iftex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 @ifnottex
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 @xref{Buffers and Windows}, for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 @end ifnottex
98812
38749a93f5a4 (Displaying Buffers): Minor wording fix.
Eli Zaretskii <eliz@gnu.org>
parents: 98794
diff changeset
772 low-level primitives that give you more precise control. All of these
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773 functions work by calling @code{set-window-buffer}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 Do not use the functions in this section in order to make a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 current so that a Lisp program can access or modify it; they are too
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777 drastic for that purpose, since they change the display of buffers in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 windows, which would be gratuitous and surprise the user. Instead, use
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 Buffer}), which designate buffers as current for programmed access
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781 without affecting the display of buffers in windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783 @deffn Command switch-to-buffer buffer-or-name &optional norecord
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 This function makes @var{buffer-or-name} the current buffer, and also
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785 displays the buffer in the selected window. This means that a human can
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 see the buffer and subsequent keyboard commands will apply to it.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
788 the current buffer but does not display it in the selected window;
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
789 see @ref{Current Buffer}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
791 If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
792 buffer using @code{other-buffer}. If @var{buffer-or-name} is a string
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
793 that does not identify an existing buffer, then a new buffer by that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
794 name is created. The major mode for the new buffer is set according to
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103458
diff changeset
795 the variable @code{major-mode}; see @ref{Auto Major Mode}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
797 When the selected window is the minibuffer window or is strongly
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
798 dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
99441
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
799 @code{pop-to-buffer} (see below) to display the buffer in some other
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
800 window.
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
801
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 Normally the specified buffer is put at the front of the buffer list
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 (both the selected frame's buffer list and the frame-independent buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804 list). This affects the operation of @code{other-buffer}. However, if
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 List}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 The @code{switch-to-buffer} function is often used interactively, as
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 the binding of @kbd{C-x b}. It is also used frequently in programs. It
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 returns the buffer that it switched to.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 The next two functions are similar to @code{switch-to-buffer}, except
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 for the described features.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
817 This function makes the buffer specified by @var{buffer-or-name} current
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
818 and displays it in a window not currently selected, using the function
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
819 @code{pop-to-buffer} (see below).
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 The currently selected window is absolutely never used to do the job.
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
822 If the selected window already displays @var{buffer-or-name}, then it
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
823 continues to do so, but another window is nonetheless found to display
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
824 it in as well.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 This function updates the buffer list just like @code{switch-to-buffer}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827 unless @var{norecord} is non-@code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829
107946
0cc12709c3b5 Fix @deffn without category.
Juri Linkov <juri@jurta.org>
parents: 106815
diff changeset
830 @deffn Command pop-to-buffer buffer-or-name &optional other-window norecord
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
831 This command makes @var{buffer-or-name} the current buffer and switches
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
832 to it in some window, preferably not the window previously selected.
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
833 The ``popped-to'' window becomes the selected window. Its frame is
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
834 given the X server's focus, if possible; see @ref{Input Focus}. The
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
835 return value is the buffer that was switched to.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
836
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
837 If @var{buffer-or-name} is @code{nil}, that means to choose some other
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
838 buffer, but you don't specify which. If @var{buffer-or-name} is a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
839 string that does not name an existing buffer, a buffer by that name is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
840 created. The major mode for the new buffer is set according to the
104626
caa79498564a * subr.el (default-mode-line-format, default-header-line-format)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 103458
diff changeset
841 variable @code{major-mode}. @xref{Auto Major Mode}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
843 If either of the variables @code{display-buffer-reuse-frames} or
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
844 @code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
845 window in any visible frame already displaying the buffer; if there is
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
846 one, it selects and returns that window. If no such window exists and
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
847 @code{pop-up-frames} is non-@code{nil}, it creates a new frame and
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
848 displays the buffer in it. Otherwise, @code{pop-to-buffer} operates
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
849 entirely within the selected frame. (If the selected frame has just a
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
850 minibuffer, @code{pop-to-buffer} operates within the most recently
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
851 selected frame that was not just a minibuffer.)
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
853 If the variable @code{pop-up-windows} is non-@code{nil}, windows may be
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
854 split to create a new window that is different from the original window.
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
855 For details, see @ref{Choosing Window}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858 creates another window even if @var{buffer-or-name} is already visible
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 in the selected window. Thus @var{buffer-or-name} could end up
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 displayed in two windows. On the other hand, if @var{buffer-or-name} is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 already displayed in the selected window and @var{other-window} is
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
862 @code{nil}, then the selected window is considered sufficient for
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
863 displaying @var{buffer-or-name}, so that nothing needs to be done.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 All the variables that affect @code{display-buffer} affect
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866 @code{pop-to-buffer} as well. @xref{Choosing Window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868 This function updates the buffer list just like @code{switch-to-buffer}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 unless @var{norecord} is non-@code{nil}.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
870 @end deffn
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871
99128
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
872 @deffn Command replace-buffer-in-windows &optional buffer-or-name
98843
296e6dfba21e (Choosing Window, Displaying Buffers): Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 98835
diff changeset
873 This function replaces @var{buffer-or-name} in all windows displaying
296e6dfba21e (Choosing Window, Displaying Buffers): Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 98835
diff changeset
874 it with some other buffer. It uses @code{other-buffer} to choose the
296e6dfba21e (Choosing Window, Displaying Buffers): Fix last changes.
Eli Zaretskii <eliz@gnu.org>
parents: 98835
diff changeset
875 other buffer. In the usual applications of this function, you
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876 don't care which other buffer is used; you just want to make sure that
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 @var{buffer-or-name} is no longer displayed.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
879 The argument @var{buffer-or-name} may be a buffer or the name of an
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
880 existing buffer and defaults to the current buffer.
99128
1b8fa7deb470 (Deleting Windows): Update documentation of delete-windows-on.
Martin Rudalics <rudalics@gmx.at>
parents: 99029
diff changeset
881
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
882 If a window displaying @var{buffer-or-name} is dedicated
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
883 (@pxref{Dedicated Windows}), and is not the only window on its frame,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
884 that window is deleted. If that window is the only window on its frame
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
885 and there are other frames left, the window's frame is deleted too. If
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
886 there are no other frames left, some other buffer is displayed in that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
887 window.
98835
4c36d8b3b766 (Choosing Window, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 98827
diff changeset
888
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889 This function returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 @node Choosing Window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893 @section Choosing a Window for Display
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 This section describes the basic facility that chooses a window to
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
896 display a buffer in---@code{display-buffer}. Higher-level functions and
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
897 commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
898 subroutine. Here we describe how to use @code{display-buffer} and how
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
899 to customize it.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
902 This command makes @var{buffer-or-name} appear in some window, but it
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
903 does not select that window and does not make the buffer specified by
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
904 @var{buffer-or-name} current. The identity of the selected window is
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
905 unaltered by this function. The argument @var{buffer-or-name} must be a
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
906 buffer or the name of an existing buffer.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
908 @var{not-this-window} non-@code{nil} means to display the specified
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
909 buffer in a window other than the selected one, even if it is already
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
910 displayed in the selected window. This can cause the buffer to appear
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
911 in two windows at once. Otherwise, if @var{buffer-or-name} is already
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
912 being displayed in any window, that is good enough, so this function
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
913 does nothing.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 @code{display-buffer} returns the window chosen to display
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916 @var{buffer-or-name}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
918 If the optional argument @var{frame} is non-@code{nil}, it specifies
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
919 which frames to check when deciding whether the buffer is already
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
920 displayed. If the buffer is already displayed in some window on one of
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
921 these frames, @code{display-buffer} simply returns that window. Here
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
922 are the possible values of @var{frame}:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924 @itemize @bullet
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
926 @code{nil} means consider windows on the selected frame.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927 (Actually, the last non-minibuffer frame.)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
929 @code{t} means consider windows on all frames.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
931 @code{visible} means consider windows on all visible frames.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
933 0 means consider windows on all visible or iconified frames.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934 @item
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
935 A frame means consider windows on that frame only.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936 @end itemize
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938 Precisely how @code{display-buffer} finds or creates a window depends on
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 the variables described below.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
942 @defopt display-buffer-reuse-frames
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
943 If this variable is non-@code{nil}, @code{display-buffer} searches
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
944 visible and iconified frames for a window displaying
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
945 @var{buffer-or-name}. If there is such a window, @code{display-buffer}
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
946 makes that window's frame visible and raises it if necessary, and
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
947 returns the window. If there is no such window or
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
948 @code{display-buffer-reuse-frames} is @code{nil}, the behavior of
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
949 @code{display-buffer} is determined by the variables described next.
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
950 @end defopt
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
951
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
952 @defopt pop-up-windows
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
953 This variable specifies whether @code{display-buffer} is allowed to
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
954 split (@pxref{Splitting Windows}) an existing window. If this variable
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
955 is non-@code{nil}, @code{display-buffer} tries to split the largest or
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
956 least recently used window on the selected frame. (If the selected
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
957 frame is a minibuffer-only frame, @code{display-buffer} tries to split a
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
958 window on another frame instead.) If this variable is @code{nil} or the
99911
c69004518f91 (Choosing Window, Selecting Windows): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99760
diff changeset
959 variable @code{pop-up-frames} (see below) is non-@code{nil},
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
960 @code{display-buffer} does not split any window.
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
961 @end defopt
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
962
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
963 @defopt split-window-preferred-function
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
964 This variable must specify a function with one argument, which is a
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
965 window. The @code{display-buffer} routines will call this function with
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
966 one or more candidate windows when they look for a window to split. The
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
967 function is expected to split that window and return the new window. If
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
968 the function returns @code{nil}, this means that the argument window
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
969 cannot (or shall not) be split.
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
970
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
971 The default value of @code{split-window-preferred-function} is the
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
972 function @code{split-window-sensibly} described below. If you
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
973 customize this option, bear in mind that the @code{display-buffer}
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
974 routines may call your function up to two times when trying to split a
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
975 window. The argument of the first call is the largest window on the
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
976 chosen frame (as returned by @code{get-largest-window}). If that call
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
977 fails to return a live window, your function is called a second time
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
978 with the least recently used window on that frame (as returned by
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
979 @code{get-lru-window}).
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
980
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
981 The function specified by this option may try to split any other window
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
982 instead of the argument window. Note that the window selected at the
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
983 time @code{display-buffer} was invoked is still selected when your
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
984 function is called. Hence, you can split the selected window (instead
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
985 of the largest or least recently used one) by simply ignoring the window
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
986 argument in the body of your function. You can even choose to not split
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
987 any window as long as the return value of your function specifies a live
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
988 window or @code{nil}, but you are not encouraged to do so
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
989 unconditionally. If you want @code{display-buffer} to never split any
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
990 windows, set @code{pop-up-windows} to @code{nil}.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
991 @end defopt
98812
38749a93f5a4 (Displaying Buffers): Minor wording fix.
Eli Zaretskii <eliz@gnu.org>
parents: 98794
diff changeset
992
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
993 @defun split-window-sensibly window
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
994 This function takes a window as argument and tries to split that window
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
995 in a suitable way. The two variables described next are useful for
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
996 tuning the behavior of this function.
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
997 @end defun
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
998
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999 @defopt split-height-threshold
103197
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1000 This variable specifies whether @code{split-window-sensibly} may split
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1001 windows vertically. If it is an integer, @code{split-window-sensibly}
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1002 tries to vertically split a window only if it has at least this many
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1003 lines. If the window has less lines, splitting fails, or the value of
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1004 this variable is @code{nil}, @code{split-window-sensibly} will try to
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1005 split the window horizontally, subject to restrictions of
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1006 @code{split-width-threshold} (see below). If splitting horizontally
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1007 fails too and the window is the only window on its frame,
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1008 @code{split-window-sensibly} will try to split the window vertically
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1009 disregarding the value of @code{split-height-threshold}. If this fails
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1010 as well, @code{split-window-sensibly} returns @code{nil}.
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1011
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1012 @code{split-window-sensibly} does not split vertically a window whose
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1013 height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1014 a window only if the space taken up by that window can accommodate two
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1015 windows one above the other that are both at least
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1016 @code{window-min-height} lines tall. Moreover, if the window that shall
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1017 be split has a mode line, @code{split-window-sensibly} does not split
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1018 the window unless the new window can accomodate a mode line too.
98812
38749a93f5a4 (Displaying Buffers): Minor wording fix.
Eli Zaretskii <eliz@gnu.org>
parents: 98794
diff changeset
1019 @end defopt
38749a93f5a4 (Displaying Buffers): Minor wording fix.
Eli Zaretskii <eliz@gnu.org>
parents: 98794
diff changeset
1020
38749a93f5a4 (Displaying Buffers): Minor wording fix.
Eli Zaretskii <eliz@gnu.org>
parents: 98794
diff changeset
1021 @defopt split-width-threshold
103197
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1022 This variable specifies whether @code{split-window-sensibly} may split
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1023 windows horizontally. If it is an integer, @code{split-window-sensibly}
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1024 tries to horizontally split a window only if it has at least this many
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1025 columns. If it is @code{nil}, @code{split-window-sensibly} will not
0c6730c52151 (Choosing Window): Don't explicitly refer to
Martin Rudalics <rudalics@gmx.at>
parents: 103189
diff changeset
1026 split the window horizontally. (It still might split the window
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1027 vertically, though, see above.)
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1028
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1029 @code{split-window-sensibly} does not split horizontally a window if
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
1030 that window's width is fixed (@pxref{Resizing Windows}). Also, it
103189
7b19ba744cfe (Choosing Window): Fix rewrite of window splitting section.
Martin Rudalics <rudalics@gmx.at>
parents: 103186
diff changeset
1031 horizontally splits a window only if the space that window takes up can
103186
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
1032 accommodate two windows side by side that are both at least
622683e27798 (Choosing Window): Describe split-window-sensibly
Martin Rudalics <rudalics@gmx.at>
parents: 103177
diff changeset
1033 @code{window-min-width} columns wide.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036 @defopt even-window-heights
98944
e3bf6a4e1aa6 More wording fixes from RMS.
Eli Zaretskii <eliz@gnu.org>
parents: 98928
diff changeset
1037 This variable specifies whether @code{display-buffer} should even out
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1038 window heights if the buffer gets displayed in an existing window, above
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1039 or beneath another window. If @code{even-window-heights} is
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1040 non-@code{nil}, the default, window heights will be evened out. If
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1041 either of the involved window has fixed height (@pxref{Resizing
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1042 Windows}) or @code{even-window-heights} is @code{nil}, the original
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1043 window heights will be left alone.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 @c Emacs 19 feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047 @defopt pop-up-frames
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1048 This variable specifies whether @code{display-buffer} should make new
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1049 frames. If it is non-@code{nil}, @code{display-buffer} looks for a
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1050 window already displaying @var{buffer-or-name} on any visible or
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1051 iconified frame. If it finds such a window, it makes that window's
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1052 frame visible and raises it if necessary, and returns the window.
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1053 Otherwise it makes a new frame, unless the variable's value is
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1054 @code{graphic-only} and the selected frame is not on a graphic display.
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1055 @xref{Frames}, for more information.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1056
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1057 Note that the value of @code{pop-up-windows} does not matter if
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1058 @code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1059 @code{nil}, then @code{display-buffer} either splits a window or reuses
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1060 one.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 @c Emacs 19 feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 @defopt pop-up-frame-function
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 This variable specifies how to make a new frame if @code{pop-up-frames}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 is non-@code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1068 The value of this variable must be a function of no arguments. When
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069 @code{display-buffer} makes a new frame, it does so by calling that
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1070 function, which should return a frame. The default value of this
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1071 variable is a function that creates a frame using the parameters
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1072 specified by @code{pop-up-frame-alist} described next.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 @defopt pop-up-frame-alist
100846
d74b83c02d95 (Choosing Window): Say that pop-up-frame-alist
Martin Rudalics <rudalics@gmx.at>
parents: 100555
diff changeset
1076 This variable holds an alist specifying frame parameters used by the
d74b83c02d95 (Choosing Window): Say that pop-up-frame-alist
Martin Rudalics <rudalics@gmx.at>
parents: 100555
diff changeset
1077 default value of @code{pop-up-frame-function} for making new frames.
d74b83c02d95 (Choosing Window): Say that pop-up-frame-alist
Martin Rudalics <rudalics@gmx.at>
parents: 100555
diff changeset
1078 @xref{Frame Parameters}, for more information about frame parameters.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081 @defopt special-display-buffer-names
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1082 A list of buffer names identifying buffers that should be displayed
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1083 specially. If the name of @var{buffer-or-name} is in this list,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1084 @code{display-buffer} handles the buffer specially. By default, special
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1085 display means to give the buffer a dedicated frame.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1087 If an element is a list, instead of a string, then the @sc{car} of that
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1088 list is the buffer name, and the rest of that list says how to create
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1089 the frame. There are two possibilities for the rest of that list (its
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1090 @sc{cdr}): It can be an alist, specifying frame parameters, or it can
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 contain a function and arguments to give to it. (The function's first
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 argument is always the buffer to be displayed; the arguments from the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 list come after that.)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095 For example:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098 (("myfile" (minibuffer) (menu-bar-lines . 0)))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 @noindent
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102 specifies to display a buffer named @samp{myfile} in a dedicated frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105 The list of frame parameters can also use the phony frame parameters
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106 @code{same-frame} and @code{same-window}. If the specified frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 parameters include @code{(same-window . @var{value})} and @var{value}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108 is non-@code{nil}, that means to display the buffer in the current
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 selected window. Otherwise, if they include @code{(same-frame .
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 @var{value})} and @var{value} is non-@code{nil}, that means to display
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 the buffer in a new window in the currently selected frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 @defopt special-display-regexps
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1115 A list of regular expressions specifying buffers that should be
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 displayed specially. If the buffer's name matches any of the regular
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117 expressions in this list, @code{display-buffer} handles the buffer
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1118 specially. By default, special display means to give the buffer a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1119 dedicated frame.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1121 If an element is a list, instead of a string, then the @sc{car} of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 list is the regular expression, and the rest of the list says how to
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1123 create the frame. See @code{special-display-buffer-names} above.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126 @defun special-display-p buffer-name
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 This function returns non-@code{nil} if displaying a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 named @var{buffer-name} with @code{display-buffer} would
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 create a special frame. The value is @code{t} if it would
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130 use the default frame parameters, or else the specified list
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131 of frame parameters.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
1134 @defopt special-display-function
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135 This variable holds the function to call to display a buffer specially.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 It receives the buffer as an argument, and should return the window in
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1137 which it is displayed. The default value of this variable is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1138 @code{special-display-popup-frame}, see below.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
1139 @end defopt
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1140
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1141 @defun special-display-popup-frame buffer &optional args
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1142 This function tries to make @var{buffer} visible in a frame of its own.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1143 If @var{buffer} is already displayed in some window, it makes that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1144 window's frame visible and raises it. Otherwise, it creates a frame
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1145 that is dedicated to @var{buffer}. The return value is the window used
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1146 to display @var{buffer}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 If @var{args} is an alist, it specifies frame parameters for the new
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1149 frame. If @var{args} is a list whose @sc{car} is a symbol, then
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1150 @code{(car @var{args})} is called as a function to actually create and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1151 set up the frame; it is called with @var{buffer} as first argument, and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1152 @code{(cdr @var{args})} as additional arguments.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1153
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1154 This function always uses an existing window displaying @var{buffer},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1155 whether or not it is in a frame of its own; but if you set up the above
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1156 variables in your init file, before @var{buffer} was created, then
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1157 presumably the window was previously made by this function.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1158 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160 @defopt special-display-frame-alist
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161 @anchor{Definition of special-display-frame-alist}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162 This variable holds frame parameters for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 @code{special-display-popup-frame} to use when it creates a frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166 @defopt same-window-buffer-names
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 A list of buffer names for buffers that should be displayed in the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 selected window. If the buffer's name is in this list,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169 @code{display-buffer} handles the buffer by switching to it in the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 selected window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 @defopt same-window-regexps
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174 A list of regular expressions that specify buffers that should be
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 displayed in the selected window. If the buffer's name matches any of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 the regular expressions in this list, @code{display-buffer} handles the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 buffer by switching to it in the selected window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180 @defun same-window-p buffer-name
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181 This function returns @code{t} if displaying a buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 named @var{buffer-name} with @code{display-buffer} would
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 put it in the selected window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186 @c Emacs 19 feature
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
1187 @defopt display-buffer-function
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 This variable is the most flexible way to customize the behavior of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 @code{display-buffer}. If it is non-@code{nil}, it should be a function
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1190 that @code{display-buffer} calls to do the work. The function should
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1191 accept two arguments, the first two arguments that @code{display-buffer}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1192 received. It should choose or create a window, display the specified
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 buffer in it, and then return the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1195 This variable takes precedence over all the other options described
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1196 above.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103257
diff changeset
1197 @end defopt
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1199 If all options described above fail to produce a suitable window,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1200 @code{display-buffer} tries to reuse an existing window. As a last
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1201 resort, it will try to display @var{buffer-or-name} on a separate frame.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1202 In that case, the value of @code{pop-up-frames} is disregarded.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1203
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1204 @node Dedicated Windows
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1205 @section Dedicated Windows
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 @cindex dedicated window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1207
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1208 Functions for displaying a buffer can be told to not use specific
103458
29ff3f8b1e3b (Dedicated Windows): Fix typo.
Martin Rudalics <rudalics@gmx.at>
parents: 103273
diff changeset
1209 windows by marking these windows as @dfn{dedicated} to their buffers.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1210 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1211 window for displaying another buffer in it. @code{get-lru-window} and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1212 @code{get-largest-window} (@pxref{Selecting Windows}) do not consider
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1213 dedicated windows as candidates when their @var{dedicated} argument is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1214 non-@code{nil}. The behavior of @code{set-window-buffer}
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1215 (@pxref{Buffers and Windows}) with respect to dedicated windows is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1216 slightly different, see below.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1217
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1218 When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1219 a dedicated window and that window is the only window on its frame, it
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1220 deletes the window's frame too, provided there are other frames left.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1221 @code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1222 delete all dedicated windows showing its buffer argument. When such a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1223 window is the only window on its frame, that frame is deleted, provided
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1224 there are other frames left. If there are no more frames left, some
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1225 other buffer is displayed in the window, and the window is marked as
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1226 non-dedicated.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1227
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1228 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1229 dedicated window, any such window usually gets deleted too, since
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1230 @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1231 up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1232 selected window if it is dedicated to that buffer. If, however, that
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1233 window is the only window on its frame, @code{bury-buffer} displays
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1234 another buffer in it and iconifies the frame.
98835
4c36d8b3b766 (Choosing Window, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 98827
diff changeset
1235
4c36d8b3b766 (Choosing Window, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 98827
diff changeset
1236 @defun window-dedicated-p &optional window
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1237 This function returns non-@code{nil} if @var{window} is dedicated to its
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1238 buffer and @code{nil} otherwise. More precisely, the return value is
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1239 the value assigned by the last call of @code{set-window-dedicated-p} for
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1240 @var{window} or @code{nil} if that function was never called with
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1241 @var{window} as its argument. The default for @var{window} is the
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1242 selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 @defun set-window-dedicated-p window flag
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1246 This function marks @var{window} as dedicated to its buffer if
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
1247 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1248
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1249 As a special case, if @var{flag} is @code{t}, @var{window} becomes
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1250 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1251 signals an error when the window it acts upon is strongly dedicated to
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1252 its buffer and does not already display the buffer it is asked to
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1253 display. Other functions do not treat @code{t} differently from any
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1254 non-@code{nil} value.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 @node Window Point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258 @section Windows and Point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 @cindex window position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260 @cindex window point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261 @cindex position in window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262 @cindex point in window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1264 Each window has its own value of point (@pxref{Point}), independent of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1265 the value of point in other windows displaying the same buffer. This
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1266 makes it useful to have multiple windows showing one buffer.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 @itemize @bullet
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 The window point is established when a window is first created; it is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271 initialized from the buffer's point, or from the window point of another
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272 window opened on the buffer if such a window exists.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 Selecting a window sets the value of point in its buffer from the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276 window's value of point. Conversely, deselecting a window sets the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1277 window's value of point from that of the buffer. Thus, when you switch
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1278 between windows that display a given buffer, the point value for the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1279 selected window is in effect in the buffer, while the point values for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1280 the other windows are stored in those windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1281
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282 @item
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 As long as the selected window displays the current buffer, the window's
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 point and the buffer's point always move together; they remain equal.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285 @end itemize
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287 @cindex cursor
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1288 As far as the user is concerned, point is where the cursor is, and
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 when the user switches to another buffer, the cursor jumps to the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290 position of point in that buffer.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 @defun window-point &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 This function returns the current position of point in @var{window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294 For a nonselected window, this is the value point would have (in that
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1295 window's buffer) if that window were selected. The default for
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1296 @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298 When @var{window} is the selected window and its buffer is also the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 current buffer, the value returned is the same as point in that buffer.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1300 Strictly speaking, it would be more correct to return the ``top-level''
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1301 value of point, outside of any @code{save-excursion} forms. But that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1302 value is hard to find.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 @defun set-window-point window position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 This function positions point in @var{window} at position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 @var{position} in @var{window}'s buffer. It returns @var{position}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309 If @var{window} is selected, and its buffer is current,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 this simply does @code{goto-char}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312
99441
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1313 @defvar window-point-insertion-type
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1314 This variable specifies the marker insertion type (@pxref{Marker
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1315 Insertion Types}) of @code{window-point}. The default is @code{nil},
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1316 so @code{window-point} will stay behind text inserted there.
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1317 @end defvar
910601b61dec (Displaying Buffers): For switch-to-buffer mention that
Martin Rudalics <rudalics@gmx.at>
parents: 99438
diff changeset
1318
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1319 @node Window Start and End
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1320 @section The Window Start and End Positions
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 @cindex window start position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1323 Each window maintains a marker used to keep track of a buffer position
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 that specifies where in the buffer display should start. This position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 is called the @dfn{display-start} position of the window (or just the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326 @dfn{start}). The character after this position is the one that appears
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 at the upper left corner of the window. It is usually, but not
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 inevitably, at the beginning of a text line.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329
92148
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1330 After switching windows or buffers, and in some other cases, if the
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1331 window start is in the middle of a line, Emacs adjusts the window
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1332 start to the start of a line. This prevents certain operations from
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1333 leaving the window start at a meaningless point within a line. This
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1334 feature may interfere with testing some Lisp code by executing it
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1335 using the commands of Lisp mode, because they trigger this
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1336 readjustment. To test such code, put it into a command and bind the
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1337 command to a key.
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1338
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 @defun window-start &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340 @cindex window top line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 This function returns the display-start position of window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 @var{window}. If @var{window} is @code{nil}, the selected window is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 used. For example,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 (window-start)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 @result{} 7058
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 When you create a window, or display a different buffer in it, the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353 display-start position is set to a display-start position recently used
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1354 for the same buffer, or to @code{point-min} if the buffer doesn't have
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1355 any.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 Redisplay updates the window-start position (if you have not specified
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1358 it explicitly since the previous redisplay)---to make sure point appears
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1359 on the screen. Nothing except redisplay automatically changes the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1360 window-start position; if you move point, do not expect the window-start
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1361 position to change in response until after the next redisplay.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363 For a realistic example of using @code{window-start}, see the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 description of @code{count-lines}. @xref{Definition of count-lines}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1367 @cindex window end position
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 @defun window-end &optional window update
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1369 This function returns the position where display of its buffer ends in
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1370 @var{window}. The default for @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 Simply changing the buffer text or moving point does not update the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 value that @code{window-end} returns. The value is updated only when
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 Emacs redisplays and redisplay completes without being preempted.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 If the last redisplay of @var{window} was preempted, and did not finish,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 Emacs does not know the position of the end of display in that window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 In that case, this function returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 If @var{update} is non-@code{nil}, @code{window-end} always returns an
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1381 up-to-date value for where display ends, based on the current
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1382 @code{window-start} value. If a previously saved value of that position
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1383 is still valid, @code{window-end} returns that value; otherwise it
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1384 computes the correct value by scanning the buffer text.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 Even if @var{update} is non-@code{nil}, @code{window-end} does not
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 attempt to scroll the display if point has moved off the screen, the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 way real redisplay would do. It does not alter the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 @code{window-start} value. In effect, it reports where the displayed
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390 text will end if scrolling is not required.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393 @defun set-window-start window position &optional noforce
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 This function sets the display-start position of @var{window} to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395 @var{position} in @var{window}'s buffer. It returns @var{position}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 The display routines insist that the position of point be visible when a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 buffer is displayed. Normally, they change the display-start position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 (that is, scroll the window) whenever necessary to make point visible.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 However, if you specify the start position with this function using
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 @code{nil} for @var{noforce}, it means you want display to start at
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 @var{position} even if that would put the location of point off the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 screen. If this does place point off screen, the display routines move
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404 point to the left margin on the middle line in the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405
92148
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1406 For example, if point @w{is 1} and you set the start of the window
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1407 @w{to 37}, the start of the next line, point will be ``above'' the top
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1408 of the window. The display routines will automatically move point if
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1409 it is still 1 when redisplay occurs. Here is an example:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413 ;; @r{Here is what @samp{foo} looks like before executing}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 ;; @r{the @code{set-window-start} expression.}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418 ---------- Buffer: foo ----------
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 @point{}This is the contents of buffer foo.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 2
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 3
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 4
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423 5
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 6
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 ---------- Buffer: foo ----------
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 (set-window-start
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430 (selected-window)
92148
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1431 (save-excursion
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1432 (goto-char 1)
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1433 (forward-line 1)
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1434 (point)))
f991f10f15ec Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 87649
diff changeset
1435 @result{} 37
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 ;; @r{Here is what @samp{foo} looks like after executing}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 ;; @r{the @code{set-window-start} expression.}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441 ---------- Buffer: foo ----------
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 2
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443 3
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 @point{}4
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 5
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 6
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447 ---------- Buffer: foo ----------
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 If @var{noforce} is non-@code{nil}, and @var{position} would place point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 off screen at the next redisplay, then redisplay computes a new window-start
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453 position that works well with point, and thus @var{position} is not used.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456 @defun pos-visible-in-window-p &optional position window partially
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457 This function returns non-@code{nil} if @var{position} is within the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458 range of text currently visible on the screen in @var{window}. It
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1459 returns @code{nil} if @var{position} is scrolled vertically out of view.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1460 Locations that are partially obscured are not considered visible unless
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1461 @var{partially} is non-@code{nil}. The argument @var{position} defaults
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1462 to the current position of point in @var{window}; @var{window}, to the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1463 selected window. If @var{position} is @code{t}, that means to check the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1464 last visible position in @var{window}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466 The @code{pos-visible-in-window-p} function considers only vertical
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467 scrolling. If @var{position} is out of view only because @var{window}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 non-@code{nil} anyway. @xref{Horizontal Scrolling}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471 If @var{position} is visible, @code{pos-visible-in-window-p} returns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1473 non-@code{nil}, and the character following @var{position} is fully
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475 @var{x} and @var{y} are the pixel coordinates relative to the top left
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1476 corner of the window; otherwise it returns an extended list of the form
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1477 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1478 where @var{rtop} and @var{rbot} specify the number of off-window pixels
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1479 at the top and bottom of the row at @var{position}, @var{rowh} specifies
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1480 the visible height of that row, and @var{vpos} specifies the vertical
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1481 position (zero-based row number) of that row.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 Here is an example:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487 ;; @r{If point is off the screen now, recenter it now.}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 (or (pos-visible-in-window-p
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 (point) (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 (recenter 0))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495 @defun window-line-height &optional line window
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1496 This function returns the height of text line @var{line} in
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1497 @var{window}. If @var{line} is one of @code{header-line} or
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1498 @code{mode-line}, @code{window-line-height} returns information about
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1499 the corresponding line of the window. Otherwise, @var{line} is a text
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1500 line number starting from 0. A negative number counts from the end of
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1501 the window. The default for @var{line} is the current line in
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1502 @var{window}; the default for @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 If the display is not up to date, @code{window-line-height} returns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 to obtain related information.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508 If there is no line corresponding to the specified @var{line},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509 @code{window-line-height} returns @code{nil}. Otherwise, it returns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511 where @var{height} is the height in pixels of the visible part of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 line, @var{vpos} and @var{ypos} are the vertical position in lines and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513 pixels of the line relative to the top of the first text line, and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514 @var{offbot} is the number of off-window pixels at the bottom of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 text line. If there are off-window pixels at the top of the (first)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 text line, @var{ypos} is negative.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1517 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1519 @node Textual Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520 @section Textual Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1521 @cindex textual scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 @cindex scrolling textually
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1523
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1524 @dfn{Textual scrolling} means moving the text up or down through a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1525 window. It works by changing the value of the window's display-start
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1526 location. It may also change the value of @code{window-point} to keep
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1527 point on the screen.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1528
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529 Textual scrolling was formerly called ``vertical scrolling,'' but we
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1530 changed its name to distinguish it from the new vertical fractional
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531 scrolling feature (@pxref{Vertical Scrolling}).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 In the commands @code{scroll-up} and @code{scroll-down}, the directions
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 ``up'' and ``down'' refer to the motion of the text in the buffer at which
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535 you are looking through the window. Imagine that the text is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536 written on a long roll of paper and that the scrolling commands move the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 paper up and down. Thus, if you are looking at text in the middle of a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 buffer and repeatedly call @code{scroll-down}, you will eventually see
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 the beginning of the buffer.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541 Some people have urged that the opposite convention be used: they
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 imagine that the window moves over text that remains in place. Then
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 ``down'' commands would take you to the end of the buffer. This view is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 more consistent with the actual relationship between windows and the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545 text in the buffer, but it is less like what the user sees. The
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546 position of a window on the terminal does not move, and short scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1547 commands clearly move the text up or down on the screen. We have chosen
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 names that fit the user's point of view.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1549
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1550 The textual scrolling functions (aside from
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1551 @code{scroll-other-window}) have unpredictable results if the current
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1552 buffer is different from the buffer that is displayed in the selected
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1553 window. @xref{Current Buffer}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1554
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1555 If the window contains a row which is taller than the height of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1556 window (for example in the presence of a large image), the scroll
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1557 functions will adjust the window's vertical scroll position to scroll
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1558 the partially visible row. To disable this feature, Lisp code may bind
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1559 the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1560 Scrolling}).
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1561
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1562 @deffn Command scroll-up &optional count
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1563 This function scrolls the text in the selected window upward
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1564 @var{count} lines. If @var{count} is negative, scrolling is actually
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1565 downward.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1566
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1567 If @var{count} is @code{nil} (or omitted), then the length of scroll
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1568 is @code{next-screen-context-lines} lines less than the usable height of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1569 the window (not counting its mode line).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1570
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1571 @code{scroll-up} returns @code{nil}, unless it gets an error
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1572 because it can't scroll any further.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1573 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1574
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1575 @deffn Command scroll-down &optional count
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1576 This function scrolls the text in the selected window downward
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1577 @var{count} lines. If @var{count} is negative, scrolling is actually
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1578 upward.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1579
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1580 If @var{count} is omitted or @code{nil}, then the length of the scroll
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1581 is @code{next-screen-context-lines} lines less than the usable height of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1582 the window (not counting its mode line).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1583
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 @code{scroll-down} returns @code{nil}, unless it gets an error because
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585 it can't scroll any further.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588 @deffn Command scroll-other-window &optional count
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 This function scrolls the text in another window upward @var{count}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 lines. Negative values of @var{count}, or @code{nil}, are handled
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591 as in @code{scroll-up}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 You can specify which buffer to scroll by setting the variable
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595 already displayed, @code{scroll-other-window} displays it in some
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596 window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 When the selected window is the minibuffer, the next window is normally
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 the one at the top left corner. You can specify a different window to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600 scroll, when the minibuffer is selected, by setting the variable
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 @code{minibuffer-scroll-window}. This variable has no effect when any
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602 other window is selected. When it is non-@code{nil} and the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 minibuffer is selected, it takes precedence over
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1604 @code{other-window-scroll-buffer}. @xref{Definition of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 minibuffer-scroll-window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607 When the minibuffer is active, it is the next window if the selected
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608 window is the one at the bottom right corner. In this case,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609 @code{scroll-other-window} attempts to scroll the minibuffer. If the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610 minibuffer contains just one line, it has nowhere to scroll to, so the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 line reappears after the echo area momentarily displays the message
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 @samp{Beginning of buffer}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 @c Emacs 19 feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 @defvar other-window-scroll-buffer
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1618 which buffer's window to scroll.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 @defopt scroll-margin
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 This option specifies the size of the scroll margin---a minimum number
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623 of lines between point and the top or bottom of a window. Whenever
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 point gets within this many lines of the top or bottom of the window,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625 redisplay scrolls the text automatically (if possible) to move point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 out of the margin, closer to the center of the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 @defopt scroll-conservatively
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 This variable controls how scrolling is done automatically when point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 moves off the screen (or into the scroll margin). If the value is a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632 positive integer @var{n}, then redisplay scrolls the text up to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 @var{n} lines in either direction, if that will bring point back into
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1634 proper view. This behavior is called @dfn{conservative scrolling}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635 Otherwise, scrolling happens in the usual way, under the control of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 other variables such as @code{scroll-up-aggressively} and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637 @code{scroll-down-aggressively}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639 The default value is zero, which means that conservative scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640 never happens.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 @defopt scroll-down-aggressively
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 The value of this variable should be either @code{nil} or a fraction
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645 @var{f} between 0 and 1. If it is a fraction, that specifies where on
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646 the screen to put point when scrolling down. More precisely, when a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 window scrolls down because point is above the window start, the new
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648 start position is chosen to put point @var{f} part of the window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 height from the top. The larger @var{f}, the more aggressive the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 scrolling.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 A value of @code{nil} is equivalent to .5, since its effect is to center
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653 point. This variable automatically becomes buffer-local when set in any
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654 fashion.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @defopt scroll-up-aggressively
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658 Likewise, for scrolling up. The value, @var{f}, specifies how far
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 point should be placed from the bottom of the window; thus, as with
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663 @defopt scroll-step
108366
e2da1d33db95 Fix typos (Bug#6094). From ªÞt«µp«¡n N«µmec.
Chong Yidong <cyd@stupidchicken.com>
parents: 107946
diff changeset
1664 This variable is an older variant of @code{scroll-conservatively}.
e2da1d33db95 Fix typos (Bug#6094). From ªÞt«µp«¡n N«µmec.
Chong Yidong <cyd@stupidchicken.com>
parents: 107946
diff changeset
1665 The difference is that if its value is @var{n}, that permits scrolling
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 only by precisely @var{n} lines, not a smaller number. This feature
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 does not work with @code{scroll-margin}. The default value is zero.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 @defopt scroll-preserve-screen-position
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671 If this option is @code{t}, scrolling which would move the current
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 point position out of the window chooses the new position of point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673 so that the vertical position of the cursor is unchanged, if possible.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 If it is non-@code{nil} and not @code{t}, then the scrolling functions
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 always preserve the vertical position of point, if possible.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679 @defopt next-screen-context-lines
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 The value of this variable is the number of lines of continuity to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 retain when scrolling by full screens. For example, @code{scroll-up}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 with an argument of @code{nil} scrolls so that this many lines at the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683 bottom of the window appear instead at the top. The default value is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 @code{2}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 @deffn Command recenter &optional count
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 @cindex centering point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 This function scrolls the text in the selected window so that point is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690 displayed at a specified vertical position within the window. It does
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 not ``move point'' with respect to the text.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 If @var{count} is a nonnegative number, that puts the line containing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 point @var{count} lines down from the top of the window. If
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 @var{count} is a negative number, then it counts upward from the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696 bottom of the window, so that @minus{}1 stands for the last usable
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 line in the window. If @var{count} is a non-@code{nil} list, then it
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 stands for the line in the middle of the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700 If @var{count} is @code{nil}, @code{recenter} puts the line containing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 point in the middle of the window, then clears and redisplays the entire
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702 selected frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 When @code{recenter} is called interactively, @var{count} is the raw
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707 @var{count} to 4, which positions the current line four lines from the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708 top.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710 With an argument of zero, @code{recenter} positions the current line at
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 the top of the window. This action is so handy that some people make a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 separate key binding to do this. For example,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 (defun line-to-top-of-window ()
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717 "Scroll current line to top of window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 Replaces three keystroke sequence C-u 0 C-l."
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719 (interactive)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 (recenter 0))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722 (global-set-key [kp-multiply] 'line-to-top-of-window)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727 @node Vertical Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 @section Vertical Fractional Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729 @cindex vertical fractional scrolling
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1730 @cindex vertical scroll position
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1731
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1732 @dfn{Vertical fractional scrolling} means shifting text in a window
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1733 up or down by a specified multiple or fraction of a line. Each window
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1734 has a @dfn{vertical scroll position}, which is a number, never less than
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1735 zero. It specifies how far to raise the contents of the window.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1736 Raising the window contents generally makes all or part of some lines
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1737 disappear off the top, and all or part of some other lines appear at the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1738 bottom. The usual value is zero.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1739
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1740 The vertical scroll position is measured in units of the normal line
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 height, which is the height of the default font. Thus, if the value is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742 .5, that means the window contents are scrolled up half the normal line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 height. If it is 3.3, that means the window contents are scrolled up
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 somewhat over three times the normal line height.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1746 What fraction of a line the vertical scrolling covers, or how many
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 lines, depends on what the lines contain. A value of .5 could scroll a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 line whose height is very short off the screen, while a value of 3.3
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 could scroll just part of the way through a tall line or an image.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 @defun window-vscroll &optional window pixels-p
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 This function returns the current vertical scroll position of
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1753 @var{window}. The default for @var{window} is the selected window.
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1754 If @var{pixels-p} is non-@code{nil}, the return value is measured in
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1755 pixels, rather than in units of the normal line height.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759 (window-vscroll)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 @result{} 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765 @defun set-window-vscroll window lines &optional pixels-p
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 This function sets @var{window}'s vertical scroll position to
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1767 @var{lines}. If @var{window} is @code{nil}, the selected window is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1768 used. The argument @var{lines} should be zero or positive; if not, it
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1769 is taken as zero.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1770
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 The actual vertical scroll position must always correspond
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 to an integral number of pixels, so the value you specify
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 is rounded accordingly.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 The return value is the result of this rounding.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 (set-window-vscroll (selected-window) 1.2)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781 @result{} 1.13
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 pixels. In this case, the return value is @var{lines}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 @defvar auto-window-vscroll
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 If this variable is non-@code{nil}, the line-move, scroll-up, and
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1791 scroll-down functions will automatically modify the vertical scroll
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
1792 position to scroll through display rows that are taller than the height
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1793 of the window, for example in the presence of large images.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796 @node Horizontal Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 @section Horizontal Scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 @cindex horizontal scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 @dfn{Horizontal scrolling} means shifting the image in the window left
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 or right by a specified multiple of the normal character width. Each
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802 window has a @dfn{horizontal scroll position}, which is a number, never
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 less than zero. It specifies how far to shift the contents left.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804 Shifting the window contents left generally makes all or part of some
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 characters disappear off the left, and all or part of some other
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 characters appear at the right. The usual value is zero.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 The horizontal scroll position is measured in units of the normal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809 character width, which is the width of space in the default font. Thus,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810 if the value is 5, that means the window contents are scrolled left by 5
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 times the normal character width. How many characters actually
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812 disappear off to the left depends on their width, and could vary from
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 line to line.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815 Because we read from side to side in the ``inner loop,'' and from top
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 to bottom in the ``outer loop,'' the effect of horizontal scrolling is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817 not like that of textual or vertical scrolling. Textual scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 involves selection of a portion of text to display, and vertical
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 scrolling moves the window contents contiguously; but horizontal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 scrolling causes part of @emph{each line} to go off screen.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1821
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1822 Usually, no horizontal scrolling is in effect; then the leftmost
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1823 column is at the left edge of the window. In this state, scrolling to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 the right is meaningless, since there is no data to the left of the edge
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825 to be revealed by it; so this is not allowed. Scrolling to the left is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1826 allowed; it scrolls the first columns of text off the edge of the window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1827 and can reveal additional columns on the right that were truncated
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1828 before. Once a window has a nonzero amount of leftward horizontal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1829 scrolling, you can scroll it back to the right, but only so far as to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1830 reduce the net horizontal scroll to zero. There is no limit to how far
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831 left you can scroll, but eventually all the text will disappear off the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832 left edge.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834 @vindex auto-hscroll-mode
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 If @code{auto-hscroll-mode} is set, redisplay automatically alters
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1836 the horizontal scrolling of a window as necessary to ensure that point
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1837 is always visible. However, you can still set the horizontal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838 scrolling value explicitly. The value you specify serves as a lower
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1839 bound for automatic scrolling, i.e. automatic scrolling will not
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1840 scroll a window to a column less than the specified one.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1841
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1842 @deffn Command scroll-left &optional count set-minimum
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1843 This function scrolls the selected window @var{count} columns to the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844 left (or to the right if @var{count} is negative). The default
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 for @var{count} is the window width, minus 2.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847 The return value is the total amount of leftward horizontal scrolling in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848 effect after the change---just like the value returned by
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1849 @code{window-hscroll} (below).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1850
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1851 Once you scroll a window as far right as it can go, back to its normal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1852 position where the total leftward scrolling is zero, attempts to scroll
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1853 any farther right have no effect.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1854
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856 the lower bound for automatic scrolling; that is, automatic scrolling
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857 will not scroll a window to a column less than the value returned by
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858 this function. Interactive calls pass non-@code{nil} for
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 @var{set-minimum}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862 @deffn Command scroll-right &optional count set-minimum
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 This function scrolls the selected window @var{count} columns to the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 right (or to the left if @var{count} is negative). The default
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 for @var{count} is the window width, minus 2. Aside from the direction
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1866 of scrolling, this works just like @code{scroll-left}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1867 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869 @defun window-hscroll &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 This function returns the total leftward horizontal scrolling of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 @var{window}---the number of columns by which the text in @var{window}
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1872 is scrolled left past the left margin. The default for
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1873 @var{window} is the selected window.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1874
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1875 The return value is never negative. It is zero when no horizontal
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1876 scrolling has been done in @var{window} (which is usually the case).
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1877
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1880 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881 (window-hscroll)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 @result{} 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 (scroll-left 5)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886 @result{} 5
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889 (window-hscroll)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 @result{} 5
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1895 @defun set-window-hscroll window columns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1896 This function sets horizontal scrolling of @var{window}. The value of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1897 @var{columns} specifies the amount of scrolling, in terms of columns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1898 from the left margin. The argument @var{columns} should be zero or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1899 positive; if not, it is taken as zero. Fractional values of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1900 @var{columns} are not supported at present.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1901
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1902 Note that @code{set-window-hscroll} may appear not to work if you test
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1903 it by evaluating a call with @kbd{M-:} in a simple way. What happens
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1904 is that the function sets the horizontal scroll value and returns, but
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1905 then redisplay adjusts the horizontal scrolling to make point visible,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1906 and this overrides what the function did. You can observe the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1907 function's effect if you call it while point is sufficiently far from
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1908 the left margin that it will remain visible.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1909
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1910 The value returned is @var{columns}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1911
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1912 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1913 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1914 (set-window-hscroll (selected-window) 10)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1915 @result{} 10
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1916 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1917 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1918 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1919
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1920 Here is how you can determine whether a given position @var{position}
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
1921 is off the screen due to horizontal scrolling:
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1922
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1923 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1924 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1925 (defun hscroll-on-screen (window position)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1926 (save-excursion
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1927 (goto-char position)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1928 (and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1929 (>= (- (current-column) (window-hscroll window)) 0)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1930 (< (- (current-column) (window-hscroll window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1931 (window-width window)))))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1932 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1933 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1934
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1935 @node Size of Window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1936 @section The Size of a Window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1937 @cindex window size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1938 @cindex size of window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1939
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1940 An Emacs window is rectangular, and its size information consists of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1941 the height (the number of lines) and the width (the number of character
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1942 positions in each line). The mode line is included in the height. But
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1943 the width does not count the scroll bar or the column of @samp{|}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1944 characters that separates side-by-side windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1945
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1946 The following three functions return size information about a window:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1947
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1948 @defun window-height &optional window
105542
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1949 This function returns the number of lines in @var{window} (by default
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1950 the selected window), including any mode line and header line.
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1951 The result is almost always less than the value of @code{frame-height}
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1952 for the associated frame, because the latter also includes any echo
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1953 area. Depending on the toolkit in use, the frame height can also
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1954 include the menu bar and tool bar (@pxref{Size and Position}).
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1955 Therefore in general it is not straightforward to compare window and
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1956 frame heights (see @code{window-full-height-p} below).
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1957
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1958 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1959 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1960 (window-height)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1961 @result{} 23
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1962 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1963 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1964 (split-window-vertically)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1965 @result{} #<window 4 on windows.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1966 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1967 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1968 (window-height)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1969 @result{} 11
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1970 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1971 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1972 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1973
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1974 @defun window-body-height &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1975 Like @code{window-height} but the value does not include the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1976 mode line (if any) or the header line (if any).
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1977 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1978
105542
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1979 @defun window-full-height-p &optional window
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1980 This function returns non-@code{nil} if @var{window} is as tall as the
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1981 frame that contains it. The default for @var{window} is the selected
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1982 window.
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1983 @end defun
ea0b3808f728 (Size of Window): The relationship between window and frame heights is
Glenn Morris <rgm@gnu.org>
parents: 104626
diff changeset
1984
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1985 @defun window-width &optional window
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1986 This function returns the number of columns in @var{window}. The
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
1987 default for @var{window} is the selected window.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1988
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1989 The return value does not include the window's scroll bar or the column
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1990 of @samp{|} characters that separates side-by-side windows. Moreover,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1991 the return value does not include the space used for displaying fringes
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1992 and margins. Hence you cannot, in general, compare the return values of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1993 @code{window-width} and @code{frame-width} for equality to determine
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1994 whether a window is a wide as the containing frame. Use the function
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
1995 @code{window-full-width-p}, see below, instead.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1996
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1997 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1998 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1999 (window-width)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2000 @result{} 80
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2001 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2002 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2003 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2004
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2005 @defun window-full-width-p &optional window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2006 This function returns non-@code{nil} if @var{window} is as wide as the
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2007 frame that contains it; otherwise @code{nil}. The default for
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2008 @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2009 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2010
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2011 @defun window-edges &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2012 This function returns a list of the edge coordinates of @var{window}.
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2013 The default for @var{window} is the selected window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2014
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2015 The order of the list is @code{(@var{left} @var{top} @var{right}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2016 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2017 the frame. The element @var{right} of the value is one more than the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2018 rightmost column used by @var{window}, and @var{bottom} is one more than
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2019 the bottommost row used by @var{window} and its mode-line.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2020
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2021 The edges include the space used by the window's scroll bar, display
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2022 margins, fringes, header line, and mode line, if it has them. Also,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2023 if the window has a neighbor on the right, its right edge value
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2024 includes the width of the separator line between the window and that
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2025 neighbor. Since the width of the window does not include this
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2026 separator, the width does not usually equal the difference between the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2027 right and left edges.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2028 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2029
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2030 @defun window-inside-edges &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2031 This is similar to @code{window-edges}, but the edge values
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2032 it returns include only the text area of the window. They
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2033 do not include the header line, mode line, scroll bar or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2034 vertical separator, fringes, or display margins.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2035 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2036
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2037 Here are the results obtained on a typical 24-line terminal with just
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2038 one window, with menu bar enabled:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2039
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2040 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2041 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2042 (window-edges (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2043 @result{} (0 1 80 23)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2044 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2045 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2046 (window-inside-edges (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2047 @result{} (0 1 80 22)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2048 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2049 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2050
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2051 @noindent
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2052 The bottom edge is at line 23 because the last line is the echo area.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2053 The bottom inside edge is at line 22, which is the window's mode line.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2054
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2055 If @var{window} is at the upper left corner of its frame, and there is
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2056 no menu bar, then @var{bottom} returned by @code{window-edges} is the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2057 same as the value of @code{(window-height)}, @var{right} is almost the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2058 same as the value of @code{(window-width)}, and @var{top} and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2059 @var{left} are zero. For example, the edges of the following window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2060 are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2061 columns, the last column of the window (column 7) holds a border
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2062 rather than text. The last row (row 4) holds the mode line, shown
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2063 here with @samp{xxxxxxxxx}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2064
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2065 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2066 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2067 0
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2068 _______
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2069 0 | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2070 | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2071 | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2072 | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2073 xxxxxxxxx 4
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2074
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2075 7
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2076 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2077 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2078
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2079 In the following example, let's suppose that the frame is 7
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2080 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2081 and the edges of the right window are @w{@samp{4 0 7 3}}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2082 The inside edges of the left window are @w{@samp{0 0 3 2}},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2083 and the inside edges of the right window are @w{@samp{4 0 7 2}},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2084
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2085 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2086 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2087 ___ ___
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2088 | | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2089 | | |
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2090 xxxxxxxxx
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2091
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2092 0 34 7
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2093 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2094 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2095
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2096 @defun window-pixel-edges &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2097 This function is like @code{window-edges} except that, on a graphical
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2098 display, the edge values are measured in pixels instead of in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2099 character lines and columns.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2100 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2101
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2102 @defun window-inside-pixel-edges &optional window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2103 This function is like @code{window-inside-edges} except that, on a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2104 graphical display, the edge values are measured in pixels instead of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2105 in character lines and columns.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2106 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2107
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2108 @node Resizing Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2109 @section Changing the Size of a Window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2110 @cindex window resizing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2111 @cindex resize window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2112 @cindex changing window size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2113 @cindex window size, changing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2114
99760
690624ab76e0 (Displaying Buffers, Vertical Scrolling)
Martin Rudalics <rudalics@gmx.at>
parents: 99693
diff changeset
2115 The window size functions fall into two classes: high-level commands
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2116 that change the size of windows and low-level functions that access
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2117 window size. Emacs does not permit overlapping windows or gaps between
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2118 windows, so resizing a window always affects at least one other window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2119
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2120 @deffn Command enlarge-window size &optional horizontal
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2121 This function makes the selected window @var{size} lines taller by
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2122 stealing lines from windows above or below. In a first round, it takes
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2123 lines from one window at a time until that window is
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2124 @code{window-min-height} lines tall, then takes from another. If, at
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2125 the end of the first round, the selected window is still not tall
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2126 enough, @code{enlarge-window} starts a second round, where it deletes
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2127 windows above or below the selected one.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2128
98894
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2129 If @var{horizontal} is non-@code{nil}, this function makes the window
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2130 @var{size} columns wider, stealing columns instead of lines. If a
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2131 window from which columns are stolen shrinks below
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2132 @code{window-min-width} columns, that window disappears.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2133
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2134 If the requested size would exceed that of the window's frame, then the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2135 function makes the window occupy the entire height (or width) of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2136 frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2137
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2138 If there are various other windows from which lines or columns can be
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2139 stolen, and some of them specify fixed size (using
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2140 @code{window-size-fixed}, see below), they are left untouched while
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2141 other windows are ``robbed.'' If it would be necessary to alter the
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2142 size of a fixed-size window, @code{enlarge-window} gets an error
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2143 instead.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2144
98960
3240f5341524 (Resizing Windows): Minor wording fix.
Martin Rudalics <rudalics@gmx.at>
parents: 98944
diff changeset
2145 If @var{size} is negative, this function shrinks the selected window by
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2146 @minus{}@var{size} lines or columns. If that makes the window smaller
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2147 than the minimum size (@code{window-min-height} and
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2148 @code{window-min-width}), then @code{enlarge-window} deletes the window.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2149
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2150 @code{enlarge-window} returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2151 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2152
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2153 @deffn Command enlarge-window-horizontally columns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2154 This function makes the selected window @var{columns} wider.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2155 It could be defined as follows:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2156
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2157 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2158 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2159 (defun enlarge-window-horizontally (columns)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2160 (interactive "p")
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2161 (enlarge-window columns t))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2162 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2163 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2164 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2165
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2166 @deffn Command shrink-window size &optional horizontal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2167 This function is like @code{enlarge-window} but negates the argument
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2168 @var{size}, making the selected window smaller by giving lines (or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2169 columns) to the other windows. If the window shrinks below
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2170 @code{window-min-height} or @code{window-min-width}, then it disappears.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2171
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2172 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2173 lines or columns.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2174 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2175
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2176 @deffn Command shrink-window-horizontally columns
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2177 This function makes the selected window @var{columns} narrower.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2178 It could be defined as follows:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2179
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2180 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2181 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2182 (defun shrink-window-horizontally (columns)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2183 (interactive "p")
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2184 (shrink-window columns t))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2185 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2186 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2187 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2188
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2189 @defun adjust-window-trailing-edge window delta horizontal
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2190 This function makes the selected window @var{delta} lines taller or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2191 @var{delta} columns wider, by moving the bottom or right edge. This
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2192 function does not delete other windows; if it cannot make the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2193 requested size adjustment, it signals an error. On success, this
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2194 function returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2195 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2196
103458
29ff3f8b1e3b (Dedicated Windows): Fix typo.
Martin Rudalics <rudalics@gmx.at>
parents: 103273
diff changeset
2197 @deffn Command fit-window-to-buffer &optional window max-height min-height
29ff3f8b1e3b (Dedicated Windows): Fix typo.
Martin Rudalics <rudalics@gmx.at>
parents: 103273
diff changeset
2198 This command makes @var{window} the right height to display its
100555
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2199 contents exactly. The default for @var{window} is the selected window.
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2200
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2201 The optional argument @var{max-height} specifies the maximum height the
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2202 window is allowed to be; @code{nil} means use the maximum permissible
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2203 height of a window on @var{window}'s frame. The optional argument
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2204 @var{min-height} specifies the minimum height for the window; @code{nil}
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2205 means use @code{window-min-height}. All these height values include the
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2206 mode line and/or header line.
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2207
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2208 This function can delete windows when their height shrinks below
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2209 @var{min-height}. It returns non-@code{nil} if it orderly resized
66984afb4693 (Windows): Rewrite description of
Martin Rudalics <rudalics@gmx.at>
parents: 99911
diff changeset
2210 @var{window}, and @code{nil} otherwise.
103458
29ff3f8b1e3b (Dedicated Windows): Fix typo.
Martin Rudalics <rudalics@gmx.at>
parents: 103273
diff changeset
2211 @end deffn
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2212
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2213 @deffn Command shrink-window-if-larger-than-buffer &optional window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2214 This command shrinks @var{window} vertically to be as small as possible
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2215 while still showing the full contents of its buffer---but not less than
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2216 @code{window-min-height} lines. The default for @var{window} is
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2217 the selected window.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2218
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2219 However, this command does nothing if the window is already too small to
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2220 display the whole text of the buffer, or if part of the contents are
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2221 currently scrolled off screen, or if the window is not the full width of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2222 its frame, or if the window is the only window in its frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2223
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2224 This command returns non-@code{nil} if it actually shrank the window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2225 and @code{nil} otherwise.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2226 @end deffn
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2227
99029
da79c29252c4 (Displaying Buffers): Reword documentation of pop-to-buffer.
Martin Rudalics <rudalics@gmx.at>
parents: 98960
diff changeset
2228 @cindex fixed-size window
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2229 @defvar window-size-fixed
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2230 If this variable is non-@code{nil}, in a given buffer, then the size of
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2231 any window displaying that buffer remains fixed unless you either
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2232 explicitly change it or Emacs has no other choice.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2233
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2234 If the value is @code{height}, then only the window's height is fixed;
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2235 if the value is @code{width}, then only the window's width is fixed.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2236 Any other non-@code{nil} value fixes both the width and the height.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2237
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2238 This variable automatically becomes buffer-local when set.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2239
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2240 Explicit size-change functions such as @code{enlarge-window}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2241 get an error if they would have to change a window size which is fixed.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2242 Therefore, when you want to change the size of such a window,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2243 you should bind @code{window-size-fixed} to @code{nil}, like this:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2244
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2245 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2246 (let ((window-size-fixed nil))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2247 (enlarge-window 10))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2248 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2249
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2250 Deleting an adjacent window or changing the frame size may change the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2251 size of a fixed-size window, if there is no other alternative.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2252 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2253
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2254 @cindex minimum window size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2255 The following two variables constrain the window-structure-changing
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2256 functions to a minimum height and width.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2257
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2258 @defopt window-min-height
98944
e3bf6a4e1aa6 More wording fixes from RMS.
Eli Zaretskii <eliz@gnu.org>
parents: 98928
diff changeset
2259 The value of this variable specifies how short a window may become
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2260 before it is automatically deleted. Making a window smaller than
98894
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2261 @code{window-min-height} automatically deletes it, and no window may be
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2262 created shorter than this. The value is measured in line units. When
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2263 the window wants a mode line and/or a header line, they are counted as
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2264 one line each. The default value is @code{4}. A value less than
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2265 @code{1} is ignored.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2266 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2267
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2268 @defopt window-min-width
98944
e3bf6a4e1aa6 More wording fixes from RMS.
Eli Zaretskii <eliz@gnu.org>
parents: 98928
diff changeset
2269 The value of this variable specifies how narrow a window may become
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2270 before it is automatically deleted. Making a window smaller than
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2271 @code{window-min-width} automatically deletes it, and no window may be
98894
1e370d7d742a (Resizing Windows): Remove var{} around window in
Martin Rudalics <rudalics@gmx.at>
parents: 98843
diff changeset
2272 created narrower than this. The value is measured in characters and
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2273 includes any fringes or the scroll bar. The default value is @code{10}.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2274 A value less than @code{2} is ignored.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2275 @end defopt
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2276
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2277 @cindex balancing window sizes
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2278 Emacs provides two functions to balance windows, that is, to even out
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2279 the sizes of windows on the same frame. The minibuffer window and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2280 fixed-size windows are not resized by these functions.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2281
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2282 @deffn Command balance-windows &optional window-or-frame
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2283 This function balances windows in a way that gives more space to
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2284 full-width and/or full-height windows. If @var{window-or-frame}
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2285 specifies a frame, it balances all windows on that frame. If
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2286 @var{window-or-frame} specifies a window, it balances this window and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2287 its ``siblings'' only. Think of a sibling as the other (original or
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2288 new) window with respect to the present one, involved in the process of
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
2289 splitting; see @ref{Splitting Windows}. Since a sibling may have been
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2290 split again, a window can have more than one sibling.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2291 @end deffn
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2292
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2293 @deffn Command balance-windows-area
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2294 This function attempts to give all windows on the selected frame
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2295 approximately the same share of the screen area. This means that
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2296 full-width or full-height windows are not given more space than other
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2297 windows.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2298 @end deffn
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2299
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2300 @node Coordinates and Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2301 @section Coordinates and Windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2302
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2303 This section describes how to relate screen coordinates to windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2304
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2305 @defun window-at x y &optional frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2306 This function returns the window containing the specified cursor
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2307 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2308 are measured in characters and count from the top left corner of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2309 frame. If they are out of range, @code{window-at} returns @code{nil}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2310
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2311 If you omit @var{frame}, the selected frame is used.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2312 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2313
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2314 @defun coordinates-in-window-p coordinates window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2315 This function checks whether a particular frame position falls within
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2316 the window @var{window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2317
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2318 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2319 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2320 characters, and count from the top left corner of the screen or frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2321
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2322 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2323 if the coordinates are inside @var{window}. The value also indicates
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2324 what part of the window the position is in, as follows:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2325
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2326 @table @code
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2327 @item (@var{relx} . @var{rely})
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2328 The coordinates are inside @var{window}. The numbers @var{relx} and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2329 @var{rely} are the equivalent window-relative coordinates for the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2330 specified position, counting from 0 at the top left corner of the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2331 window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2332
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2333 @item mode-line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2334 The coordinates are in the mode line of @var{window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2335
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2336 @item header-line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2337 The coordinates are in the header line of @var{window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2338
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2339 @item vertical-line
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2340 The coordinates are in the vertical line between @var{window} and its
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2341 neighbor to the right. This value occurs only if the window doesn't
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2342 have a scroll bar; positions in a scroll bar are considered outside the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2343 window for these purposes.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2344
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2345 @item left-fringe
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2346 @itemx right-fringe
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2347 The coordinates are in the left or right fringe of the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2348
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2349 @item left-margin
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2350 @itemx right-margin
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2351 The coordinates are in the left or right margin of the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2352
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2353 @item nil
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2354 The coordinates are not in any part of @var{window}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2355 @end table
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2356
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2357 The function @code{coordinates-in-window-p} does not require a frame as
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2358 argument because it always uses the frame that @var{window} is on.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2359 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2360
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2361 @node Window Tree
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2362 @section The Window Tree
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2363 @cindex window tree
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2364
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2365 A @dfn{window tree} specifies the layout, size, and relationship
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2366 between all windows in one frame.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2367
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2368 @defun window-tree &optional frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2369 This function returns the window tree for frame @var{frame}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2370 If @var{frame} is omitted, the selected frame is used.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2371
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2372 The return value is a list of the form @code{(@var{root} @var{mini})},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2373 where @var{root} represents the window tree of the frame's
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2374 root window, and @var{mini} is the frame's minibuffer window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2375
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2376 If the root window is not split, @var{root} is the root window itself.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2377 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2378 @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2379 and @code{t} for a vertical split, @var{edges} gives the combined size and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2380 position of the subwindows in the split, and the rest of the elements
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2381 are the subwindows in the split. Each of the subwindows may again be
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2382 a window or a list representing a window split, and so on. The
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2383 @var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2384 similar to the value returned by @code{window-edges}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2385 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2386
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2387 @node Window Configurations
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2388 @section Window Configurations
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2389 @cindex window configurations
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2390 @cindex saving window information
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2391
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2392 A @dfn{window configuration} records the entire layout of one
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2393 frame---all windows, their sizes, which buffers they contain, how those
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2394 buffers are scrolled, and their values of point and the mark; also their
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2395 fringes, margins, and scroll bar settings. It also includes the value
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2396 of @code{minibuffer-scroll-window}. As a special exception, the window
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2397 configuration does not record the value of point in the selected window
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2398 for the current buffer. Also, the window configuration does not record
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
2399 the values of window parameters; see @ref{Window Parameters}.
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2400
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2401 You can bring back an entire frame layout by restoring a previously
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2402 saved window configuration. If you want to record the layout of all
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2403 frames instead of just one, use a frame configuration instead of a
99474
ecad25300f20 Fix usage of `see @ref'.
Eli Zaretskii <eliz@gnu.org>
parents: 99465
diff changeset
2404 window configuration; see @ref{Frame Configurations}.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2405
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2406 @defun current-window-configuration &optional frame
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2407 This function returns a new object representing @var{frame}'s current
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2408 window configuration. The default for @var{frame} is the selected
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2409 frame.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2410 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2411
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2412 @defun set-window-configuration configuration
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2413 This function restores the configuration of windows and buffers as
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2414 specified by @var{configuration}, for the frame that @var{configuration}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2415 was created for.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2416
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2417 The argument @var{configuration} must be a value that was previously
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2418 returned by @code{current-window-configuration}. The configuration is
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2419 restored in the frame from which @var{configuration} was made, whether
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2420 that frame is selected or not. This always counts as a window size
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2421 change and triggers execution of the @code{window-size-change-functions}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2422 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2423 know how to tell whether the new configuration actually differs from the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2424 old one.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2425
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2426 If the frame which @var{configuration} was saved from is dead, all this
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2427 function does is restore the three variables @code{window-min-height},
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2428 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2429 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2430
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2431 Here is a way of using this function to get the same effect
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2432 as @code{save-window-excursion}:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2433
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2434 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2435 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2436 (let ((config (current-window-configuration)))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2437 (unwind-protect
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2438 (progn (split-window-vertically nil)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2439 @dots{})
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2440 (set-window-configuration config)))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2441 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2442 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2443 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2444
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2445 @defspec save-window-excursion forms@dots{}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2446 This special form records the window configuration, executes @var{forms}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2447 in sequence, then restores the earlier window configuration. The window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2448 configuration includes, for each window, the value of point and the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2449 portion of the buffer that is visible. It also includes the choice of
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2450 selected window. However, it does not include the value of point in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2451 the current buffer; use @code{save-excursion} also, if you wish to
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2452 preserve that.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2453
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2454 Don't use this construct when @code{save-selected-window} is sufficient.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2455
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2456 Exit from @code{save-window-excursion} always triggers execution of
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2457 @code{window-size-change-functions}. (It doesn't know how to tell
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2458 whether the restored configuration actually differs from the one in
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2459 effect at the end of the @var{forms}.)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2460
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2461 The return value is the value of the final form in @var{forms}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2462 For example:
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2463
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2464 @example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2465 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2466 (split-window)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2467 @result{} #<window 25 on control.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2468 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2469 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2470 (setq w (selected-window))
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2471 @result{} #<window 19 on control.texi>
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2472 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2473 @group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2474 (save-window-excursion
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2475 (delete-other-windows w)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2476 (switch-to-buffer "foo")
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2477 'do-something)
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2478 @result{} do-something
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2479 ;; @r{The screen is now split again.}
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2480 @end group
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2481 @end example
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2482 @end defspec
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2483
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2484 @defun window-configuration-p object
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2485 This function returns @code{t} if @var{object} is a window configuration.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2486 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2487
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2488 @defun compare-window-configurations config1 config2
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2489 This function compares two window configurations as regards the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2490 structure of windows, but ignores the values of point and mark and the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2491 saved scrolling positions---it can return @code{t} even if those
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2492 aspects differ.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2493
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2494 The function @code{equal} can also compare two window configurations; it
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2495 regards configurations as unequal if they differ in any respect, even a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2496 saved point or mark.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2497 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2498
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2499 @defun window-configuration-frame config
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2500 This function returns the frame for which the window configuration
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2501 @var{config} was made.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2502 @end defun
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2503
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2504 Other primitives to look inside of window configurations would make
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2505 sense, but are not implemented because we did not need them. See the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2506 file @file{winner.el} for some more operations on windows
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2507 configurations.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2508
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2509 @node Window Parameters
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2510 @section Window Parameters
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2511 @cindex window parameters
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2512
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2513 This sections describes how window parameters can be used to associate
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2514 additional information with windows.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2515
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2516 @defun window-parameter window parameter
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2517 This function returns @var{window}'s value for @var{parameter}. The
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2518 default for @var{window} is the selected window. If @var{window}
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2519 has no setting for @var{parameter}, this function returns @code{nil}.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2520 @end defun
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2521
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2522 @defun window-parameters &optional window
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2523 This function returns all parameters of @var{window} and their values.
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2524 The default for @var{window} is the selected window. The return value
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2525 is an association list of elements of the form @code{(@var{parameter}
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2526 . @var{value})}.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2527 @end defun
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2528
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2529 @defun set-window-parameter window parameter value
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2530 This function sets @var{window}'s value of @var{parameter} to
99613
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2531 @var{value} and returns @var{value}. The default for @var{window}
785924da433d (Splitting Windows, Deleting Windows)
Martin Rudalics <rudalics@gmx.at>
parents: 99474
diff changeset
2532 is the selected window.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2533 @end defun
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2534
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2535 Currently, window parameters are not saved in window configurations and
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2536 consequently not restored by @code{set-window-configuration}. Hence,
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2537 any change of a parameter introduced via @code{set-window-parameter} can
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2538 be undone only by invoking @code{set-window-parameter} for the same
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2539 parameter again. Since @code{save-window-excursion} relies on window
99465
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2540 configurations (@pxref{Window Configurations}), window parameters are
3bf4c25d3b4b (Basic Windows, Splitting Windows)
Eli Zaretskii <eliz@gnu.org>
parents: 99441
diff changeset
2541 not saved and restored by that special form, either.
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2542
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2543 @node Window Hooks
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2544 @section Hooks for Window Scrolling and Changes
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2545 @cindex hooks for window operations
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2546
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2547 This section describes how a Lisp program can take action whenever a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2548 window displays a different part of its buffer or a different buffer.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2549 There are three actions that can change this: scrolling the window,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2550 switching buffers in the window, and changing the size of the window.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2551 The first two actions run @code{window-scroll-functions}; the last runs
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2552 @code{window-size-change-functions}.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2553
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2554 @defvar window-scroll-functions
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2555 This variable holds a list of functions that Emacs should call before
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2556 redisplaying a window with scrolling. Displaying a different buffer in
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2557 the window also runs these functions.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2558
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2559 This variable is not a normal hook, because each function is called with
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2560 two arguments: the window, and its new display-start position.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2561
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2562 These functions must be careful in using @code{window-end}
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2563 (@pxref{Window Start and End}); if you need an up-to-date value, you
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2564 must use the @var{update} argument to ensure you get it.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2565
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2566 @strong{Warning:} don't use this feature to alter the way the window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2567 is scrolled. It's not designed for that, and such use probably won't
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2568 work.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2569 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2570
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2571 @defvar window-size-change-functions
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2572 This variable holds a list of functions to be called if the size of any
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2573 window changes for any reason. The functions are called just once per
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2574 redisplay, and just once for each frame on which size changes have
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2575 occurred.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2576
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2577 Each function receives the frame as its sole argument. There is no
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2578 direct way to find out which windows on that frame have changed size, or
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2579 precisely how. However, if a size-change function records, at each
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2580 call, the existing windows and their sizes, it can also compare the
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2581 present sizes and the previous sizes.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2582
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2583 Creating or deleting windows counts as a size change, and therefore
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2584 causes these functions to be called. Changing the frame size also
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2585 counts, because it changes the sizes of the existing windows.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2586
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2587 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2588 Configurations}) in these functions, because that always counts as a
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2589 size change, and it would cause these functions to be called over and
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2590 over. In most cases, @code{save-selected-window} (@pxref{Selecting
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2591 Windows}) is what you need here.
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2592 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2593
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2594 @defvar window-configuration-change-hook
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2595 A normal hook that is run every time you change the window configuration
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2596 of an existing frame. This includes splitting or deleting windows,
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2597 changing the sizes of windows, or displaying a different buffer in a
99438
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2598 window.
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2599
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2600 The buffer-local part of this hook is run once per each window on the
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2601 affected frame, with the relevant window selected and its buffer
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2602 current. The global part is run once for the modified frame, with that
5743d4e279a5 (Windows): Update entries.
Martin Rudalics <rudalics@gmx.at>
parents: 99128
diff changeset
2603 frame selected.
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2604 @end defvar
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2605
99693
3c7c38bba785 (Window Hooks): Remove *-end-trigger-functions vars, which are
Chong Yidong <cyd@stupidchicken.com>
parents: 99613
diff changeset
2606 In addition, you can use @code{jit-lock-register} to register a Font
103237
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
2607 Lock fontification function, which will be called whenever parts of a
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
2608 buffer are (re)fontified because a window was scrolled or its size
0c05518365a6 (Selecting Windows): Clarify descriptions of
Martin Rudalics <rudalics@gmx.at>
parents: 103197
diff changeset
2609 changed. @xref{Other Font Lock Variables}.
99693
3c7c38bba785 (Window Hooks): Remove *-end-trigger-functions vars, which are
Chong Yidong <cyd@stupidchicken.com>
parents: 99613
diff changeset
2610
84112
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2611 @ignore
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2612 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
7087f74a4f1d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2613 @end ignore