annotate lispref/windows.texi @ 51442:4c41fd813bd1

*** empty log message ***
author Juanma Barranquero <lekktu@gmail.com>
date Tue, 03 Jun 2003 23:35:20 +0000
parents b65aa1d740eb
children f954442d2253
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c Free Software Foundation, Inc.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Windows, Frames, Buffers, Top
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 This chapter describes most of the functions and variables related to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 Emacs windows. See @ref{Display}, for information on how text is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 displayed in windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @menu
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
15 * Basic Windows:: Basic information on using windows.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
16 * Splitting Windows:: Splitting one window into two windows.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
17 * Deleting Windows:: Deleting a window gives its space to other windows.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
18 * Selecting Windows:: The selected window is the one that you edit in.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
19 * Cyclic Window Ordering:: Moving around the existing windows.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
20 * Buffers and Windows:: Each window displays the contents of a buffer.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
21 * Displaying Buffers:: Higher-lever functions for displaying a buffer
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
22 and choosing a window for it.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
23 * Choosing Window:: How to choose a window for displaying a buffer.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
24 * Window Point:: Each window has its own location of point.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
25 * Window Start:: The display-start position controls which text
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
26 is on-screen in the window.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
27 * Textual Scrolling:: Moving text up and down through the window.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
28 * Vertical Scrolling:: Moving the contents up and down on the window.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
29 * Horizontal Scrolling:: Moving the contents sideways on the window.
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
30 * Size of Window:: Accessing the size of a window.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
31 * Resizing Windows:: Changing the size of a window.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
32 * Coordinates and Windows:: Converting coordinates to windows.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
33 * Window Configurations:: Saving and restoring the state of the screen.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
34 * Window Hooks:: Hooks for scrolling, window size changes,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
35 redisplay going past a certain point,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
36 or window configuration changes.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @end menu
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @node Basic Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @section Basic Concepts of Emacs Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 @cindex window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @cindex selected window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
44 A @dfn{window} in Emacs is the physical area of the screen in which a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
45 buffer is displayed. The term is also used to refer to a Lisp object that
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 represents that screen area in Emacs Lisp. It should be
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 clear from the context which is meant.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
49 Emacs groups windows into frames. A frame represents an area of
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
50 screen available for Emacs to use. Each frame always contains at least
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
51 one window, but you can subdivide it vertically or horizontally into
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
52 multiple nonoverlapping Emacs windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
54 In each frame, at any time, one and only one window is designated as
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
55 @dfn{selected within the frame}. The frame's cursor appears in that
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
56 window. At any time, one frame is the selected frame; and the window
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
57 selected within that frame is @dfn{the selected window}. The selected
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
58 window's buffer is usually the current buffer (except when
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
59 @code{set-buffer} has been used). @xref{Current Buffer}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
60
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
61 For practical purposes, a window exists only while it is displayed in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
62 a frame. Once removed from the frame, the window is effectively deleted
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
63 and should not be used, @emph{even though there may still be references
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
64 to it} from other Lisp objects. Restoring a saved window configuration
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
65 is the only way for a window no longer on the screen to come back to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
66 life. (@xref{Deleting Windows}.)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 Each window has the following attributes:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 containing frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
74 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 window height
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
77 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 window width
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
80 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 window edges with respect to the screen or frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
83 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 the buffer it displays
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
86 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 position within the buffer at the upper left of the window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
89 @item
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
90 amount of horizontal scrolling, in columns
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
92 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
95 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 the mark
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
98 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 how recently the window was selected
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @cindex multiple windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 Users create multiple windows so they can look at several buffers at
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 once. Lisp libraries use multiple windows for a variety of reasons, but
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
105 most often to display related information. In Rmail, for example, you
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
106 can move through a summary buffer in one window while the other window
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
107 shows messages one at a time as they are reached.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 The meaning of ``window'' in Emacs is similar to what it means in the
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
110 context of general-purpose window systems such as X, but not identical.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
111 The X Window System places X windows on the screen; Emacs uses one or
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
112 more X windows as frames, and subdivides them into
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
113 Emacs windows. When you use Emacs on a character-only terminal, Emacs
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
114 treats the whole terminal screen as one frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @cindex terminal screen
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @cindex screen of terminal
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @cindex tiled windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 Most window systems support arbitrarily located overlapping windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
121 together they fill the whole screen or frame. Because of the way in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
122 which Emacs creates new windows and resizes them, not all conceivable
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
123 tilings of windows on an Emacs frame are actually possible.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
124 @xref{Splitting Windows}, and @ref{Size of Window}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @xref{Display}, for information on how the contents of the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 window's buffer are displayed in the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @defun windowp object
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
130 This function returns @code{t} if @var{object} is a window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @node Splitting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @section Splitting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @cindex splitting windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @cindex window splitting
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 The functions described here are the primitives used to split a window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 into two windows. Two higher level functions sometimes split a window,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 but not always: @code{pop-to-buffer} and @code{display-buffer}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 (@pxref{Displaying Buffers}).
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 The functions described here do not accept a buffer as an argument.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 The two ``halves'' of the split window initially display the same buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 previously visible in the window that was split.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 @deffn Command split-window &optional window size horizontal
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 This function splits @var{window} into two windows. The original
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 window @var{window} remains the selected window, but occupies only
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 part of its former screen area. The rest is occupied by a newly created
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 window which is returned as the value of this function.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152
40312
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
153 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 two side by side windows. The original window @var{window} keeps the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 leftmost @var{size} columns, and gives the rest of the columns to the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 new window. Otherwise, it splits into windows one above the other, and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @var{window} keeps the upper @var{size} lines and gives the rest of the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 lines to the new window. The original window is therefore the
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
159 left-hand or upper of the two, and the new window is the right-hand or
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 lower.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161
40312
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
162 If @var{window} is omitted or @code{nil}, then the selected window is
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 split. If @var{size} is omitted or @code{nil}, then @var{window} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 divided evenly into two parts. (If there is an odd line, it is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 allocated to the new window.) When @code{split-window} is called
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 interactively, all its arguments are @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
40312
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
168 If splitting would result in making a window that is smaller than
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
169 @code{window-min-height} or @code{window-min-width}, the function
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
170 signals an error and does not split the window at all.
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
171
473610705e03 Explain how splitting windows relates to window-min-height
Richard M. Stallman <rms@gnu.org>
parents: 39207
diff changeset
172 The following example starts with one window on a screen that is 50
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
173 lines high by 80 columns wide; then it splits the window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 (setq w (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @result{} #<window 8 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 (window-edges) ; @r{Edges in order:}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 ;; @r{Returns window created}
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
185 (setq w2 (split-window w 15))
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @result{} #<window 28 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 (window-edges w2)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @result{} (0 15 80 50) ; @r{Bottom window;}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 ; @r{top is line 15}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 (window-edges w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @result{} (0 0 80 15) ; @r{Top window}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @end smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 The screen looks like this:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @group
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
203 __________
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
204 | | line 0
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 | w |
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 |__________|
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 | | line 15
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 | w2 |
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 |__________|
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 line 50
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 column 0 column 80
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @end smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
215 Next, split the top window horizontally:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 (setq w3 (split-window w 35 t))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @result{} #<window 32 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 (window-edges w3)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @result{} (35 0 80 15) ; @r{Left edge at column 35}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 (window-edges w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @result{} (0 0 35 15) ; @r{Right edge at column 35}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 (window-edges w2)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 @end smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12125
diff changeset
236 @need 3000
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
237 Now the screen looks like this:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 column 35
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
242 __________
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
243 | | | line 0
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 | w | w3 |
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 |___|______|
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 | | line 15
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 | w2 |
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 |__________|
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 line 50
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 column 0 column 80
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @end smallexample
8926
2231664084c2 entered into RCS
Jim Blandy <jimb@redhat.com>
parents: 8516
diff changeset
253
2231664084c2 entered into RCS
Jim Blandy <jimb@redhat.com>
parents: 8516
diff changeset
254 Normally, Emacs indicates the border between two side-by-side windows
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
255 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
8926
2231664084c2 entered into RCS
Jim Blandy <jimb@redhat.com>
parents: 8516
diff changeset
256 characters. The display table can specify alternative border
2231664084c2 entered into RCS
Jim Blandy <jimb@redhat.com>
parents: 8516
diff changeset
257 characters; see @ref{Display Tables}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
260 @deffn Command split-window-vertically &optional size
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
261 This function splits the selected window into two windows, one above the
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
262 other, leaving the upper of the two windows selected, with @var{size}
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
263 lines. (If @var{size} is negative, then the lower of the two windows
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
264 gets @minus{} @var{size} lines and the upper window gets the rest, but
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
265 the upper window is still the one selected.)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26394
diff changeset
268 @deffn Command split-window-horizontally &optional size
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 This function splits the selected window into two windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 side-by-side, leaving the selected window with @var{size} columns.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
272 This function is basically an interface to @code{split-window}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
273 You could define a simplified version of the function like this:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 (defun split-window-horizontally (&optional arg)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 "Split selected window into two windows, side by side..."
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 (interactive "P")
26211
df0efa93750b Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26210
diff changeset
280 @end group
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
281 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
282 (let ((size (and arg (prefix-numeric-value arg))))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
283 (and size (< size 0)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
284 (setq size (+ (window-width) size)))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
285 (split-window nil size t)))
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @end smallexample
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @defun one-window-p &optional no-mini all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 This function returns non-@code{nil} if there is only one window. The
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 argument @var{no-mini}, if non-@code{nil}, means don't count the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 minibuffer even if it is active; otherwise, the minibuffer window is
12125
995be67f3fd1 updates for version 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12099
diff changeset
294 included, if active, in the total number of windows, which is compared
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 against one.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 The argument @var{all-frames} specifies which frames to consider. Here
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 are the possible values and their meanings:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @table @asis
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 @item @code{nil}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 Count the windows in the selected frame, plus the minibuffer used
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 by that frame even if it lies in some other frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @item @code{t}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 Count all windows in all existing frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @item @code{visible}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 Count all windows in all visible frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
311 @item 0
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
312 Count all windows in all visible or iconified frames.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
313
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @item anything else
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 Count precisely the windows in the selected frame, and no others.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @end table
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @node Deleting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @section Deleting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @cindex deleting windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 A window remains visible on its frame unless you @dfn{delete} it by
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 calling certain functions that delete windows. A deleted window cannot
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 appear on the screen, but continues to exist as a Lisp object until
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 there are no references to it. There is no way to cancel the deletion
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 of a window aside from restoring a saved window configuration
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 (@pxref{Window Configurations}). Restoring a window configuration also
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 deletes any windows that aren't part of that configuration.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 When you delete a window, the space it took up is given to one
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
332 adjacent sibling.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @defun window-live-p window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 This function returns @code{nil} if @var{window} is deleted, and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @code{t} otherwise.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7082
diff changeset
339 @strong{Warning:} Erroneous information or fatal errors may result from
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 using a deleted window as if it were live.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @deffn Command delete-window &optional window
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
344 This function removes @var{window} from display, and returns @code{nil}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
345 If @var{window} is omitted, then the selected window is deleted. An
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
346 error is signaled if there is only one window when @code{delete-window}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
347 is called.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @deffn Command delete-other-windows &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 This function makes @var{window} the only window on its frame, by
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 deleting the other windows in that frame. If @var{window} is omitted or
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @code{nil}, then the selected window is used by default.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 The return value is @code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @deffn Command delete-windows-on buffer &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 This function deletes all windows showing @var{buffer}. If there are
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 no windows showing @var{buffer}, it does nothing.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 @code{delete-windows-on} operates frame by frame. If a frame has
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 several windows showing different buffers, then those showing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @var{buffer} are removed, and the others expand to fill the space. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 all windows in some frame are showing @var{buffer} (including the case
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 where there is only one window), then the frame reverts to having a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 single window showing another buffer chosen with @code{other-buffer}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @xref{The Buffer List}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
370 The argument @var{frame} controls which frames to operate on. This
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
371 function does not use it in quite the same way as the other functions
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
372 which scan all windows; specifically, the values @code{t} and @code{nil}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
373 have the opposite of their meanings in other functions. Here are the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
374 full details:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @item
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
378 If it is @code{nil}, operate on all frames.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @item
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
380 If it is @code{t}, operate on the selected frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 If it is @code{visible}, operate on all visible frames.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
383 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
384 If it is 0, operate on all visible or iconified frames.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 If it is a frame, operate on that frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 This function always returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @node Selecting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @section Selecting Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @cindex selecting windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 When a window is selected, the buffer in the window becomes the current
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 buffer, and the cursor will appear in it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @defun selected-window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 This function returns the selected window. This is the window in
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 which the cursor appears and to which many commands apply.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @defun select-window window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 This function makes @var{window} the selected window. The cursor then
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 appears in @var{window} (on redisplay). The buffer being displayed in
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @var{window} is immediately designated the current buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 The return value is @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 (setq w (next-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 (select-window w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @result{} #<window 65 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
420 @defmac save-selected-window forms@dots{}
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
421 This macro records the selected window, executes @var{forms}
43257
a38ad9338357 (Selecting Windows): Document that save-selected-window doesn't restore
Eli Zaretskii <eliz@gnu.org>
parents: 42985
diff changeset
422 in sequence, then restores the earlier selected window (unless that
a38ad9338357 (Selecting Windows): Document that save-selected-window doesn't restore
Eli Zaretskii <eliz@gnu.org>
parents: 42985
diff changeset
423 window is no longer alive).
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
424
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
425 This macro does not save or restore anything about the sizes, arrangement
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
426 or contents of windows; therefore, if the @var{forms} change them,
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
427 the change persists.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
428
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
429 Each frame, at any time, has a window selected within the frame. This
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
430 macro saves only @emph{the} selected window; it does not save anything
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
431 about other frames. If the @var{forms} select some other frame and
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
432 alter the window selected within it, the change persists.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
433 @end defmac
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
434
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 @cindex finding windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 The following functions choose one of the windows on the screen,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 offering various criteria for the choice.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @defun get-lru-window &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 This function returns the window least recently ``used'' (that is,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 selected). The selected window is always the most recently used window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 The selected window can be the least recently used window if it is the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 only window. A newly created window becomes the least recently used
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 window until it is selected. A minibuffer window is never a candidate.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
447 The argument @var{frame} controls which windows are considered.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 If it is @code{nil}, consider windows on the selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 If it is @code{t}, consider windows on all frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 If it is @code{visible}, consider windows on all visible frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
457 If it is 0, consider windows on all visible or iconified frames.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
458 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 If it is a frame, consider windows on that frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @defun get-largest-window &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 This function returns the window with the largest area (height times
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 width). If there are no side-by-side windows, then this is the window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 with the most lines. A minibuffer window is never a candidate.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 If there are two windows of the same size, then the function returns
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
469 the window that is first in the cyclic ordering of windows (see
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 following section), starting from the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
472 The argument @var{frame} controls which set of windows to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
473 consider. See @code{get-lru-window}, above.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
39207
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
476 @cindex window that satisfies a predicate
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
477 @cindex conditional selection of windows
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
478 @defun get-window-with-predicate predicate &optional minibuf all-frames default
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
479 This function returns a window satisfying @var{predicate}. It cycles
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
480 through all visible windows using @code{walk-windows} (@pxref{Cyclic
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
481 Window Ordering}), calling @var{predicate} on each one one of them
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
482 with that window as its argument. The function returns the first
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
483 window for which @var{predicate} returns a non-@code{nil} value; if
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
484 that never happens, it returns @var{default}.
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
485
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
486 The optional arguments @var{minibuf} and @var{all-frames} specify the
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
487 set of windows to include in the scan. See the description of
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
488 @code{next-window} in @ref{Cyclic Window Ordering}, for details.
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
489 @end defun
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
490
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @node Cyclic Window Ordering
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @comment node-name, next, previous, up
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @section Cyclic Ordering of Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @cindex cyclic ordering of windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @cindex ordering of windows, cyclic
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
496 @cindex window ordering, cyclic
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 When you use the command @kbd{C-x o} (@code{other-window}) to select
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 the next window, it moves through all the windows on the screen in a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 specific cyclic order. For any given configuration of windows, this
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 order never varies. It is called the @dfn{cyclic ordering of windows}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 This ordering generally goes from top to bottom, and from left to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 right. But it may go down first or go right first, depending on the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 order in which the windows were split.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 If the first split was vertical (into windows one above each other),
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 and then the subwindows were split horizontally, then the ordering is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 left to right in the top of the frame, and then left to right in the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 next lower part of the frame, and so on. If the first split was
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 horizontal, the ordering is top to bottom in the left part, and so on.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 In general, within each set of siblings at any level in the window tree,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 the order is left to right, or top to bottom.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @defun next-window &optional window minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @cindex minibuffer window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 This function returns the window following @var{window} in the cyclic
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
518 ordering of windows. This is the window that @kbd{C-x o} would select
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
519 if typed when @var{window} is selected. If @var{window} is the only
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 window visible, then this function returns @var{window}. If omitted,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @var{window} defaults to the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 The value of the argument @var{minibuf} determines whether the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 minibuffer is included in the window order. Normally, when
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @var{minibuf} is @code{nil}, the minibuffer is included if it is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 window is active while the minibuffer is in use. @xref{Minibuffers}.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 minibuffer window even if it is not active.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 window is not included even if it is active.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 The argument @var{all-frames} specifies which frames to consider. Here
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 are the possible values and their meanings:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @table @asis
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @item @code{nil}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 Consider all the windows in @var{window}'s frame, plus the minibuffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 used by that frame even if it lies in some other frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @item @code{t}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 Consider all windows in all existing frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @item @code{visible}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 Consider all windows in all visible frames. (To get useful results, you
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 must ensure @var{window} is in a visible frame.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549
12099
66bde18bb391 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12098
diff changeset
550 @item 0
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
551 Consider all windows in all visible or iconified frames.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
552
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @item anything else
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 Consider precisely the windows in @var{window}'s frame, and no others.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @end table
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
557 This example assumes there are two windows, both displaying the
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 buffer @samp{windows.texi}:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 (selected-window)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @result{} #<window 56 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 (next-window (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @result{} #<window 52 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 (next-window (next-window (selected-window)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @result{} #<window 56 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @defun previous-window &optional window minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 This function returns the window preceding @var{window} in the cyclic
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 ordering of windows. The other arguments specify which windows to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 include in the cycle, as in @code{next-window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
582 @deffn Command other-window count &optional all-frames
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 This function selects the @var{count}th following window in the cyclic
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
584 order. If count is negative, then it moves back @minus{}@var{count}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
585 windows in the cycle, rather than forward. It returns @code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
587 The argument @var{all-frames} has the same meaning as in
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
588 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
589 is always effectively @code{nil}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
590
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 In an interactive call, @var{count} is the numeric prefix argument.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @defun walk-windows proc &optional minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 This function cycles through all windows, calling @code{proc}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 once for each window with the window as its sole argument.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 The optional arguments @var{minibuf} and @var{all-frames} specify the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 set of windows to include in the scan. See @code{next-window}, above,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 for details.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603
33656
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
604 @defun window-list &optional frame minibuf window
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
605 This function returns a list of the windows on @var{frame}, starting
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
606 with @var{window}. If @var{frame} is @code{nil} or omitted, the
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
607 selected frame is used instead; if @var{window} is @code{nil} or
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
608 omitted, the selected window is used instead.
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
609
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
610 The value of @var{minibuf} determines if the minibuffer window will be
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
611 included in the result list. If @var{minibuf} is @code{t}, the
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
612 minibuffer window will be included, even if it isn't active. If
33826
a39402e633cd Fix markup.
Dave Love <fx@gnu.org>
parents: 33656
diff changeset
613 @var{minibuf} is @code{nil} or omitted, the minibuffer window will
33656
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
614 only be included in the list if it is active. If @var{minibuf} is
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
615 neither @code{nil} nor @code{t}, the minibuffer window is not
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
616 included, whether or not it is active.
33826
a39402e633cd Fix markup.
Dave Love <fx@gnu.org>
parents: 33656
diff changeset
617 @end defun
33656
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
618
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @node Buffers and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @section Buffers and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @cindex examining windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @cindex windows, controlling precisely
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @cindex buffers, controlled in windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 This section describes low-level functions to examine windows or to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 display buffers in windows in a precisely controlled fashion.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @iftex
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 See the following section for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
630 @ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @xref{Displaying Buffers}, for
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
632 @end ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 related functions that find a window to use and specify a buffer for it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 The functions described there are easier to use than these, but they
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 employ heuristics in choosing or creating a window; use these functions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 when you need complete control.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @defun set-window-buffer window buffer-or-name
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 This function makes @var{window} display @var{buffer-or-name} as its
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
640 contents. It returns @code{nil}. This is the fundamental primitive
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
641 for changing which buffer is displayed in a window, and all ways
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
642 of doing that call this function.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 (set-window-buffer (selected-window) "foo")
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @result{} nil
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @defun window-buffer &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 This function returns the buffer that @var{window} is displaying. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @var{window} is omitted, this function returns the buffer for the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 (window-buffer)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 @result{} #<buffer windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @defun get-buffer-window buffer-or-name &optional all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 This function returns a window currently displaying
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @var{buffer-or-name}, or @code{nil} if there is none. If there are
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 several such windows, then the function returns the first one in the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 cyclic ordering of windows, starting from the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @xref{Cyclic Window Ordering}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 The argument @var{all-frames} controls which windows to consider.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 If it is @code{nil}, consider windows on the selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 If it is @code{t}, consider windows on all frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 If it is @code{visible}, consider windows on all visible frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
682 If it is 0, consider windows on all visible or iconified frames.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
683 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 If it is a frame, consider windows on that frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
688 @defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
689 This function returns a list of all the windows currently displaying
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
690 @var{buffer-or-name}.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
691
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
692 The two optional arguments work like the optional arguments of
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
693 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
694 like the single optional argument of @code{get-buffer-window}. Perhaps
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
695 we should change @code{get-buffer-window} in the future to make it
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
696 compatible with the other functions.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
697
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
698 The argument @var{all-frames} controls which windows to consider.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
699
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
700 @itemize @bullet
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
701 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
702 If it is @code{nil}, consider windows on the selected frame.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
703 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
704 If it is @code{t}, consider windows on all frames.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
705 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
706 If it is @code{visible}, consider windows on all visible frames.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
707 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
708 If it is 0, consider windows on all visible or iconified frames.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
709 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
710 If it is a frame, consider windows on that frame.
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
711 @end itemize
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
712 @end defun
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
713
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
714 @defvar buffer-display-time
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
715 This variable records the time at which a buffer was last made visible
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
716 in a window. It is always local in each buffer; each time
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
717 @code{set-window-buffer} is called, it sets this variable to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
718 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
719 When a buffer is first created, @code{buffer-display-time} starts out
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
720 with the value @code{nil}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
721 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
722
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @node Displaying Buffers
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @section Displaying Buffers in Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @cindex switching to a buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @cindex displaying a buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 In this section we describe convenient functions that choose a window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 automatically and use it to display a specified buffer. These functions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 can also split an existing window in certain circumstances. We also
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 describe variables that parameterize the heuristics used for choosing a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @iftex
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 See the preceding section for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
736 @ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @xref{Buffers and Windows}, for
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
738 @end ifnottex
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
739 low-level functions that give you more precise control. All of these
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
740 functions work by calling @code{set-window-buffer}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 Do not use the functions in this section in order to make a buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 current so that a Lisp program can access or modify it; they are too
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 drastic for that purpose, since they change the display of buffers in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
745 windows, which would be gratuitous and surprise the user. Instead, use
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
746 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
747 Buffer}), which designate buffers as current for programmed access
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
748 without affecting the display of buffers in windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @deffn Command switch-to-buffer buffer-or-name &optional norecord
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 This function makes @var{buffer-or-name} the current buffer, and also
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 displays the buffer in the selected window. This means that a human can
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 see the buffer and subsequent keyboard commands will apply to it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 the current buffer but does not display it in the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @xref{Current Buffer}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
758 If @var{buffer-or-name} does not identify an existing buffer, then a new
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
759 buffer by that name is created. The major mode for the new buffer is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
760 set according to the variable @code{default-major-mode}. @xref{Auto
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
761 Major Mode}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
763 Normally the specified buffer is put at the front of the buffer list
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
764 (both the selected frame's buffer list and the frame-independent buffer
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
765 list). This affects the operation of @code{other-buffer}. However, if
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 List}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 The @code{switch-to-buffer} function is often used interactively, as
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 the binding of @kbd{C-x b}. It is also used frequently in programs. It
43908
40be45d9645d Correct info on return values of switch-to-buffer and pop-to-buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43665
diff changeset
771 returns the buffer that it switched to.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
774 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 This function makes @var{buffer-or-name} the current buffer and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 displays it in a window not currently selected. It then selects that
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 window. The handling of the buffer is the same as in
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @code{switch-to-buffer}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
780 The currently selected window is absolutely never used to do the job.
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
781 If it is the only window, then it is split to make a distinct window for
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
782 this purpose. If the selected window is already displaying the buffer,
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
783 then it continues to do so, but another window is nonetheless found to
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
784 display it in as well.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
785
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
786 This function updates the buffer list just like @code{switch-to-buffer}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
787 unless @var{norecord} is non-@code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
790 @defun pop-to-buffer buffer-or-name &optional other-window norecord
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 This function makes @var{buffer-or-name} the current buffer and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 switches to it in some window, preferably not the window previously
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 selected. The ``popped-to'' window becomes the selected window within
43908
40be45d9645d Correct info on return values of switch-to-buffer and pop-to-buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43665
diff changeset
794 its frame. The return value is the buffer that was switched to.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 If the variable @code{pop-up-frames} is non-@code{nil},
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @code{pop-to-buffer} looks for a window in any visible frame already
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 displaying the buffer; if there is one, it returns that window and makes
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 it be selected within its frame. If there is none, it creates a new
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 frame and displays the buffer in it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 operates entirely within the selected frame. (If the selected frame has
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 just a minibuffer, @code{pop-to-buffer} operates within the most
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 recently selected frame that was not just a minibuffer.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 be split to create a new window that is different from the original
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 window. For details, see @ref{Choosing Window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 creates another window even if @var{buffer-or-name} is already visible
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 in the selected window. Thus @var{buffer-or-name} could end up
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 displayed in two windows. On the other hand, if @var{buffer-or-name} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 already displayed in the selected window and @var{other-window} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 @code{nil}, then the selected window is considered sufficient display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 for @var{buffer-or-name}, so that nothing needs to be done.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
819 All the variables that affect @code{display-buffer} affect
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
820 @code{pop-to-buffer} as well. @xref{Choosing Window}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
821
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 If @var{buffer-or-name} is a string that does not name an existing
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
823 buffer, a buffer by that name is created. The major mode for the new
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
824 buffer is set according to the variable @code{default-major-mode}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
825 @xref{Auto Major Mode}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
826
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
827 This function updates the buffer list just like @code{switch-to-buffer}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
828 unless @var{norecord} is non-@code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
831 @deffn Command replace-buffer-in-windows buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
832 This function replaces @var{buffer} with some other buffer in all
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
833 windows displaying it. The other buffer used is chosen with
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
834 @code{other-buffer}. In the usual applications of this function, you
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
835 don't care which other buffer is used; you just want to make sure that
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
836 @var{buffer} is no longer displayed.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
837
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
838 This function returns @code{nil}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
839 @end deffn
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
840
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @node Choosing Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @section Choosing a Window for Display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
844 This section describes the basic facility that chooses a window to
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 display a buffer in---@code{display-buffer}. All the higher-level
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 functions and commands use this subroutine. Here we describe how to use
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 @code{display-buffer} and how to customize it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
849 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 This command makes @var{buffer-or-name} appear in some window, like
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @code{pop-to-buffer}, but it does not select that window and does not
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 make the buffer current. The identity of the selected window is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 unaltered by this function.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 If @var{not-this-window} is non-@code{nil}, it means to display the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 specified buffer in a window other than the selected one, even if it is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 already on display in the selected window. This can cause the buffer to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 already being displayed in any window, that is good enough, so this
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 function does nothing.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 @code{display-buffer} returns the window chosen to display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 @var{buffer-or-name}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
865 If the argument @var{frame} is non-@code{nil}, it specifies which frames
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
866 to check when deciding whether the buffer is already displayed. If the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
867 buffer is already displayed in some window on one of these frames,
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
868 @code{display-buffer} simply returns that window. Here are the possible
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
869 values of @var{frame}:
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
870
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
871 @itemize @bullet
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
872 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
873 If it is @code{nil}, consider windows on the selected frame.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
874 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
875 If it is @code{t}, consider windows on all frames.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
876 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
877 If it is @code{visible}, consider windows on all visible frames.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
878 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
879 If it is 0, consider windows on all visible or iconified frames.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
880 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
881 If it is a frame, consider windows on that frame.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
882 @end itemize
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
883
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 Precisely how @code{display-buffer} finds or creates a window depends on
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 the variables described below.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887
30665
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
888 @defopt display-buffer-reuse-frames
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
889 If this variable is non-@code{nil}, @code{display-buffer} searches
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
890 existing frames for a window displaying the buffer. If the buffer is
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
891 already displayed in a window in some frame, @code{display-buffer} makes
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
892 the frame visible and raises it, to use that window. If the buffer is
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
893 not already displayed, or if @code{display-buffer-reuse-frames} is
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
894 @code{nil}, @code{display-buffer}'s behavior is determined by other
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
895 variables, described below.
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
896 @end defopt
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
897
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @defopt pop-up-windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 This variable controls whether @code{display-buffer} makes new windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 If it is non-@code{nil} and there is only one window, then that window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 is split. If it is @code{nil}, then @code{display-buffer} does not
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 split the single window, but uses it whole.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @defopt split-height-threshold
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 This variable determines when @code{display-buffer} may split a window,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 if there are multiple windows. @code{display-buffer} always splits the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 largest window if it has at least this many lines. If the largest
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 window is not this tall, it is split only if it is the sole window and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @code{pop-up-windows} is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912
34269
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
913 @defopt even-window-heights
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
914 This variable determines if @code{display-buffer} should even out window
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
915 heights if the buffer gets displayed in an existing window, above or
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
916 beneath another existing window. If @code{even-window-heights} is
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
917 @code{t}, the default, window heights will be evened out. If
48700
df6767370b43 Fix typo.
Pavel Janík <Pavel@Janik.cz>
parents: 47687
diff changeset
918 @code{even-window-heights} is @code{nil}, the original window heights
34269
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
919 will be left alone.
34307
91a288b94484 close @defopt.
Dave Love <fx@gnu.org>
parents: 34269
diff changeset
920 @end defopt
34269
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
921
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @defopt pop-up-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 This variable controls whether @code{display-buffer} makes new frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 If it is non-@code{nil}, @code{display-buffer} looks for an existing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 window already displaying the desired buffer, on any visible frame. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 it finds one, it returns that window. Otherwise it makes a new frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 The variables @code{pop-up-windows} and @code{split-height-threshold} do
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 not matter if @code{pop-up-frames} is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 splits a window or reuses one.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 @xref{Frames}, for more information.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 @defvar pop-up-frame-function
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 This variable specifies how to make a new frame if @code{pop-up-frames}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 Its value should be a function of no arguments. When
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @code{display-buffer} makes a new frame, it does so by calling that
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 function, which should return a frame. The default value of the
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
945 variable is a function that creates a frame using parameters from
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @code{pop-up-frame-alist}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
949 @defopt pop-up-frame-alist
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 This variable holds an alist specifying frame parameters used when
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 more information about frame parameters.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
953 @end defopt
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
955 @defopt special-display-buffer-names
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
956 A list of buffer names for buffers that should be displayed specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
957 If the buffer's name is in this list, @code{display-buffer} handles the
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
958 buffer specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
959
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
960 By default, special display means to give the buffer a dedicated frame.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
961
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
962 If an element is a list, instead of a string, then the @sc{car} of the
49961
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
963 list is the buffer name, and the rest of the list says how to create
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
964 the frame. There are two possibilities for the rest of the list (its
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
965 @sc{cdr}). It can be an alist, specifying frame parameters, or it can
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
966 contain a function and arguments to give to it. (The function's first
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
967 argument is always the buffer to be displayed; the arguments from the
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
968 list come after that.)
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
969
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
970 For example:
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
971
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
972 @example
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
973 (("myfile" (minibuffer) (menu-bar-lines . 0)))
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
974 @end example
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
975
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
976 @noindent
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
977 specifies to display a buffer named @samp{myfile} in a dedicated frame
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
978 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
979 @end defopt
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
980
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
981 @defopt special-display-regexps
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
982 A list of regular expressions that specify buffers that should be
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
983 displayed specially. If the buffer's name matches any of the regular
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
984 expressions in this list, @code{display-buffer} handles the buffer
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
985 specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
986
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
987 By default, special display means to give the buffer a dedicated frame.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
988
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
989 If an element is a list, instead of a string, then the @sc{car} of the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
990 list is the regular expression, and the rest of the list says how to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
991 create the frame. See above, under @code{special-display-buffer-names}.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
992 @end defopt
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
993
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
994 @defvar special-display-function
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
995 This variable holds the function to call to display a buffer specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
996 It receives the buffer as an argument, and should return the window in
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
997 which it is displayed.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
998
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
999 The default value of this variable is
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1000 @code{special-display-popup-frame}.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1001 @end defvar
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1002
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1003 @defun special-display-popup-frame buffer &rest args
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1004 This function makes @var{buffer} visible in a frame of its own. If
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1005 @var{buffer} is already displayed in a window in some frame, it makes
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1006 the frame visible and raises it, to use that window. Otherwise, it
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1007 creates a frame that will be dedicated to @var{buffer}.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1008
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1009 If @var{args} is an alist, it specifies frame parameters for the new
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1010 frame.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1011
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1012 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1013 @var{args})} is called as a function to actually create and set up the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1014 frame; it is called with @var{buffer} as first argument, and @code{(cdr
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1015 @var{args})} as additional arguments.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1016
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1017 This function always uses an existing window displaying @var{buffer},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1018 whether or not it is in a frame of its own; but if you set up the above
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1019 variables in your init file, before @var{buffer} was created, then
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1020 presumably the window was previously made by this function.
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1021 @end defun
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1022
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1023 @defopt special-display-frame-alist
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1024 This variable holds frame parameters for
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1025 @code{special-display-popup-frame} to use when it creates a frame.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1026 @end defopt
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1027
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1028 @defopt same-window-buffer-names
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1029 A list of buffer names for buffers that should be displayed in the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1030 selected window. If the buffer's name is in this list,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1031 @code{display-buffer} handles the buffer by switching to it in the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1032 selected window.
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1033 @end defopt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1034
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1035 @defopt same-window-regexps
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1036 A list of regular expressions that specify buffers that should be
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1037 displayed in the selected window. If the buffer's name matches any of
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1038 the regular expressions in this list, @code{display-buffer} handles the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1039 buffer by switching to it in the selected window.
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1040 @end defopt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1041
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 @defvar display-buffer-function
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 This variable is the most flexible way to customize the behavior of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 @code{display-buffer}. If it is non-@code{nil}, it should be a function
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 that @code{display-buffer} calls to do the work. The function should
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 accept two arguments, the same two arguments that @code{display-buffer}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 received. It should choose or create a window, display the specified
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 buffer, and then return the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 This hook takes precedence over all the other options and hooks
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 described above.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 @cindex dedicated window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 A window can be marked as ``dedicated'' to its buffer. Then
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1058 @code{display-buffer} will not try to use that window to display any
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1059 other buffer.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 @defun window-dedicated-p window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 This function returns @code{t} if @var{window} is marked as dedicated;
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 otherwise @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @defun set-window-dedicated-p window flag
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 This function marks @var{window} as dedicated if @var{flag} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 non-@code{nil}, and nondedicated otherwise.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 @node Window Point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 @section Windows and Point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 @cindex window position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 @cindex window point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 @cindex position in window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 @cindex point in window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 Each window has its own value of point, independent of the value of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 point in other windows displaying the same buffer. This makes it useful
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 to have multiple windows showing one buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 The window point is established when a window is first created; it is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 initialized from the buffer's point, or from the window point of another
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 window opened on the buffer if such a window exists.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1089 Selecting a window sets the value of point in its buffer from the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1090 window's value of point. Conversely, deselecting a window sets the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1091 window's value of point from that of the buffer. Thus, when you switch
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1092 between windows that display a given buffer, the point value for the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1093 selected window is in effect in the buffer, while the point values for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1094 the other windows are stored in those windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097 As long as the selected window displays the current buffer, the window's
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 point and the buffer's point always move together; they remain equal.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @xref{Positions}, for more details on buffer positions.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 As far as the user is concerned, point is where the cursor is, and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 when the user switches to another buffer, the cursor jumps to the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 position of point in that buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1108 @defun window-point &optional window
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 This function returns the current position of point in @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 For a nonselected window, this is the value point would have (in that
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1111 window's buffer) if that window were selected. If @var{window} is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1112 @code{nil}, the selected window is used.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 When @var{window} is the selected window and its buffer is also the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 current buffer, the value returned is the same as point in that buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 Strictly speaking, it would be more correct to return the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 ``top-level'' value of point, outside of any @code{save-excursion}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 forms. But that value is hard to find.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @defun set-window-point window position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 This function positions point in @var{window} at position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 @var{position} in @var{window}'s buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 @node Window Start
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @section The Window Start Position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 Each window contains a marker used to keep track of a buffer position
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1131 that specifies where in the buffer display should start. This position
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 is called the @dfn{display-start} position of the window (or just the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 @dfn{start}). The character after this position is the one that appears
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 at the upper left corner of the window. It is usually, but not
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 inevitably, at the beginning of a text line.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @defun window-start &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @cindex window top line
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 This function returns the display-start position of window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @var{window}. If @var{window} is @code{nil}, the selected window is
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1141 used. For example,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 (window-start)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 @result{} 7058
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1150 When you create a window, or display a different buffer in it, the
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 display-start position is set to a display-start position recently used
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 for the same buffer, or 1 if the buffer doesn't have any.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153
12596
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1154 Redisplay updates the window-start position (if you have not specified
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1155 it explicitly since the previous redisplay)---for example, to make sure
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1156 point appears on the screen. Nothing except redisplay automatically
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1157 changes the window-start position; if you move point, do not expect the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1158 window-start position to change in response until after the next
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1159 redisplay.
12596
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1160
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1161 For a realistic example of using @code{window-start}, see the
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1162 description of @code{count-lines} in @ref{Text Lines}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1165 @defun window-end &optional window update
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 This function returns the position of the end of the display in window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @var{window}. If @var{window} is @code{nil}, the selected window is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 used.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1169
11510
e5d3814e783a Update info on window-end.
Richard M. Stallman <rms@gnu.org>
parents: 8926
diff changeset
1170 Simply changing the buffer text or moving point does not update the
e5d3814e783a Update info on window-end.
Richard M. Stallman <rms@gnu.org>
parents: 8926
diff changeset
1171 value that @code{window-end} returns. The value is updated only when
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1172 Emacs redisplays and redisplay completes without being preempted.
11510
e5d3814e783a Update info on window-end.
Richard M. Stallman <rms@gnu.org>
parents: 8926
diff changeset
1173
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1174 If the last redisplay of @var{window} was preempted, and did not finish,
8516
5d76d6decb35 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 8491
diff changeset
1175 Emacs does not know the position of the end of display in that window.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1176 In that case, this function returns @code{nil}.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1177
38380
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1178 If @var{update} is non-@code{nil}, @code{window-end} always returns an
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1179 up-to-date value for where the window ends, based on the current
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1180 @code{window-start} value. If the saved value is valid,
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1181 @code{window-end} returns that; otherwise it computes the correct
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1182 value by scanning the buffer text.
38380
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1183
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1184 Even if @var{update} is non-@code{nil}, @code{window-end} does not
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1185 attempt to scroll the display if point has moved off the screen, the
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1186 way real redisplay would do. It does not alter the
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1187 @code{window-start} value. In effect, it reports where the displayed
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1188 text will end if scrolling is not required.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 @defun set-window-start window position &optional noforce
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 This function sets the display-start position of @var{window} to
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1193 @var{position} in @var{window}'s buffer. It returns @var{position}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 The display routines insist that the position of point be visible when a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 buffer is displayed. Normally, they change the display-start position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 (that is, scroll the window) whenever necessary to make point visible.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 However, if you specify the start position with this function using
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 @code{nil} for @var{noforce}, it means you want display to start at
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @var{position} even if that would put the location of point off the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 screen. If this does place point off screen, the display routines move
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 point to the left margin on the middle line in the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 For example, if point @w{is 1} and you set the start of the window @w{to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 2}, then point would be ``above'' the top of the window. The display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 routines will automatically move point if it is still 1 when redisplay
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 occurs. Here is an example:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 ;; @r{Here is what @samp{foo} looks like before executing}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 ;; @r{the @code{set-window-start} expression.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @point{}This is the contents of buffer foo.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 2
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 3
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 6
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 (set-window-start
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 (selected-window)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 (1+ (window-start)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @result{} 2
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 ;; @r{Here is what @samp{foo} looks like after executing}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 ;; @r{the @code{set-window-start} expression.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 his is the contents of buffer foo.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 2
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 3
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 @point{}4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 6
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 If @var{noforce} is non-@code{nil}, and @var{position} would place point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 off screen at the next redisplay, then redisplay computes a new window-start
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 position that works well with point, and thus @var{position} is not used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251
34390
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1252 @defun pos-visible-in-window-p &optional position window partially
33992
74b82b7ee6f8 pos-visible-in-window-p change
Dave Love <fx@gnu.org>
parents: 33826
diff changeset
1253 This function returns @code{t} if @var{position} is within the range of
34390
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1254 text currently visible on the screen in @var{window}. It returns
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1255 @code{nil} if @var{position} is scrolled vertically or horizontally out
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1256 of view. Locations that are partially obscured are not considered
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1257 visible unless @var{partially} is non-@code{nil}. The argument
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1258 @var{position} defaults to the current position of point in
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1259 @var{window}; @var{window}, to the selected window.
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1260
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1261 Here is an example:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 (or (pos-visible-in-window-p
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 (point) (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 (recenter 0))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1272 @node Textual Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1273 @section Textual Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1274 @cindex textual scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1275 @cindex scrolling textually
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1277 @dfn{Textual scrolling} means moving the text up or down though a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1278 window. It works by changing the value of the window's display-start
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1279 location. It may also change the value of @code{window-point} to keep
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1280 point on the screen.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1281
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1282 Textual scrolling was formerly called ``vertical scrolling,'' but we
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1283 changed its name to distinguish it from the new vertical fractional
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1284 scrolling feature (@pxref{Vertical Scrolling}).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 In the commands @code{scroll-up} and @code{scroll-down}, the directions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287 ``up'' and ``down'' refer to the motion of the text in the buffer at which
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 you are looking through the window. Imagine that the text is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 written on a long roll of paper and that the scrolling commands move the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 paper up and down. Thus, if you are looking at text in the middle of a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 buffer and repeatedly call @code{scroll-down}, you will eventually see
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 the beginning of the buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 Some people have urged that the opposite convention be used: they
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 imagine that the window moves over text that remains in place. Then
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 ``down'' commands would take you to the end of the buffer. This view is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 more consistent with the actual relationship between windows and the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 text in the buffer, but it is less like what the user sees. The
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299 position of a window on the terminal does not move, and short scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 commands clearly move the text up or down on the screen. We have chosen
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301 names that fit the user's point of view.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1303 The textual scrolling functions (aside from
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1304 @code{scroll-other-window}) have unpredictable results if the current
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1305 buffer is different from the buffer that is displayed in the selected
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1306 window. @xref{Current Buffer}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 @deffn Command scroll-up &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 This function scrolls the text in the selected window upward
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 @var{count} lines. If @var{count} is negative, scrolling is actually
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 downward.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 If @var{count} is @code{nil} (or omitted), then the length of scroll
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 is @code{next-screen-context-lines} lines less than the usable height of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 the window (not counting its mode line).
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1316
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 @code{scroll-up} returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @deffn Command scroll-down &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 This function scrolls the text in the selected window downward
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 @var{count} lines. If @var{count} is negative, scrolling is actually
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 upward.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 If @var{count} is omitted or @code{nil}, then the length of the scroll
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 is @code{next-screen-context-lines} lines less than the usable height of
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1327 the window (not counting its mode line).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 @code{scroll-down} returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 @deffn Command scroll-other-window &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 This function scrolls the text in another window upward @var{count}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 lines. Negative values of @var{count}, or @code{nil}, are handled
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 as in @code{scroll-up}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1337 You can specify which buffer to scroll by setting the variable
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1338 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1339 already displayed, @code{scroll-other-window} displays it in some
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1340 window.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1341
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1342 When the selected window is the minibuffer, the next window is normally
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1343 the one at the top left corner. You can specify a different window to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1344 scroll, when the minibuffer is selected, by setting the variable
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 @code{minibuffer-scroll-window}. This variable has no effect when any
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 other window is selected. @xref{Minibuffer Misc}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 When the minibuffer is active, it is the next window if the selected
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 window is the one at the bottom right corner. In this case,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350 @code{scroll-other-window} attempts to scroll the minibuffer. If the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351 minibuffer contains just one line, it has nowhere to scroll to, so the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 line reappears after the echo area momentarily displays the message
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 ``Beginning of buffer''.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 @defvar other-window-scroll-buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 which buffer to scroll.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1362 @defopt scroll-margin
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1363 This option specifies the size of the scroll margin---a minimum number
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1364 of lines between point and the top or bottom of a window. Whenever
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1365 point gets within this many lines of the top or bottom of the window,
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1366 redisplay scrolls the text automatically (if possible) to move point
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1367 out of the margin, closer to the center of the window.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1368 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1369
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1370 @defopt scroll-conservatively
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 This variable controls how scrolling is done automatically when point
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1372 moves off the screen (or into the scroll margin). If the value is a
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1373 positive integer @var{n}, then redisplay scrolls the text up to
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1374 @var{n} lines in either direction, if that will bring point back into
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1375 proper view. This action is called @dfn{conservative scrolling}.
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1376 Otherwise, scrolling happens in the usual way, under the control of
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1377 other variables such as @code{scroll-up-aggressively} and
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1378 @code{scroll-down-aggressively}.
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1379
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1380 The default value is zero, which means that conservative scrolling
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1381 never happens.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1382 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1383
42983
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1384 @defopt scroll-down-aggressively
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1385 @tindex scroll-down-aggressively
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1386 The value of this variable should be either @code{nil} or a fraction
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1387 @var{f} between 0 and 1. If it is a fraction, that specifies where on
42983
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1388 the screen to put point when scrolling down. More precisely, when a
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1389 window scrolls down because point is above the window start, the new
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1390 start position is chosen to put point @var{f} part of the window
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1391 height from the top. The larger @var{f}, the more aggressive the
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1392 scrolling.
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1393
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26394
diff changeset
1394 A value of @code{nil} is equivalent to .5, since its effect is to center
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26394
diff changeset
1395 point. This variable automatically becomes buffer-local when set in any
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26394
diff changeset
1396 fashion.
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1397 @end defopt
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1398
42983
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1399 @defopt scroll-up-aggressively
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1400 @tindex scroll-up-aggressively
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1401 Likewise, for scrolling up. The value, @var{f}, specifies how far
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1402 point should be placed from the bottom of the window; thus, as with
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1403 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1404 @end defopt
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1405
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1406 @defopt scroll-step
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1407 This variable is an older variant of @code{scroll-conservatively}. The
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1408 difference is that it if its value is @var{n}, that permits scrolling
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1409 only by precisely @var{n} lines, not a smaller number. This feature
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1410 does not work with @code{scroll-margin}. The default value is zero.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1411 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1412
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1413 @defopt scroll-preserve-screen-position
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1414 If this option is non-@code{nil}, the scroll functions move point so
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1415 that the vertical position of the cursor is unchanged, when that is
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1416 possible.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 @defopt next-screen-context-lines
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 The value of this variable is the number of lines of continuity to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 retain when scrolling by full screens. For example, @code{scroll-up}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 with an argument of @code{nil} scrolls so that this many lines at the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 bottom of the window appear instead at the top. The default value is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @code{2}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 @deffn Command recenter &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 @cindex centering point
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1429 This function scrolls the text in the selected window so that point is
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1430 displayed at a specified vertical position within the window. It does
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1431 not ``move point'' with respect to the text.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1433 If @var{count} is a nonnegative number, that puts the line containing
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1434 point @var{count} lines down from the top of the window. If
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1435 @var{count} is a negative number, then it counts upward from the
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1436 bottom of the window, so that @minus{}1 stands for the last usable
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1437 line in the window. If @var{count} is a non-@code{nil} list, then it
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1438 stands for the line in the middle of the window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 If @var{count} is @code{nil}, @code{recenter} puts the line containing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 point in the middle of the window, then clears and redisplays the entire
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 When @code{recenter} is called interactively, @var{count} is the raw
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 @var{count} to 4, which positions the current line four lines from the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 top.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1450 With an argument of zero, @code{recenter} positions the current line at
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1451 the top of the window. This action is so handy that some people make a
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1452 separate key binding to do this. For example,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 (defun line-to-top-of-window ()
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 "Scroll current line to top of window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 Replaces three keystroke sequence C-u 0 C-l."
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1459 (interactive)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 (recenter 0))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1462 (global-set-key [kp-multiply] 'line-to-top-of-window)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1467 @node Vertical Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1468 @section Vertical Fractional Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1469 @cindex Vertical Fractional Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1470
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1471 @dfn{Vertical fractional scrolling} means shifting the image in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1472 window up or down by a specified multiple or fraction of a line.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1473 Starting in Emacs 21, each window has a @dfn{vertical scroll position},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1474 which is a number, never less than zero. It specifies how far to raise
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1475 the contents of the window. Raising the window contents generally makes
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1476 all or part of some lines disappear off the top, and all or part of some
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1477 other lines appear at the bottom. The usual value is zero.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1478
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1479 The vertical scroll position is measured in units of the normal line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1480 height, which is the height of the default font. Thus, if the value is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1481 .5, that means the window contents are scrolled up half the normal line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1482 height. If it is 3.3, that means the window contents are scrolled up
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1483 somewhat over three times the normal line height.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1484
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1485 What fraction of a line the vertical scrolling covers, or how many
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1486 lines, depends on what the lines contain. A value of .5 could scroll a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1487 line whose height is very short off the screen, while a value of 3.3
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1488 could scroll just part of the way through a tall line or an image.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1489
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1490 @defun window-vscroll &optional window
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1491 This function returns the current vertical scroll position of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1492 @var{window}, If @var{window} is @code{nil}, the selected window is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1493 used.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1494
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1495 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1496 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1497 (window-vscroll)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1498 @result{} 0
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1499 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1500 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1501 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1502
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1503 @defun set-window-vscroll window lines
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1504 This function sets @var{window}'s vertical scroll position to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1505 @var{lines}. The argument @var{lines} should be zero or positive; if
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1506 not, it is taken as zero.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1507
41504
236397d27903 (Vertical Scrolling): Document what does nil mean as the first arg of
Eli Zaretskii <eliz@gnu.org>
parents: 40333
diff changeset
1508 If @var{window} is @code{nil}, the selected window is used.
236397d27903 (Vertical Scrolling): Document what does nil mean as the first arg of
Eli Zaretskii <eliz@gnu.org>
parents: 40333
diff changeset
1509
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1510 The actual vertical scroll position must always correspond
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1511 to an integral number of pixels, so the value you specify
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1512 is rounded accordingly.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1513
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1514 The return value is the result of this rounding.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1515
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1516 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1517 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1518 (set-window-vscroll (selected-window) 1.2)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1519 @result{} 1.13
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1520 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1521 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1522 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1523
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 @node Horizontal Scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @section Horizontal Scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 @cindex horizontal scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1528 @dfn{Horizontal scrolling} means shifting the image in the window left
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1529 or right by a specified multiple of the normal character width. Each
42895
20ea28bd07ff Minor correction.
Richard M. Stallman <rms@gnu.org>
parents: 42868
diff changeset
1530 window has a @dfn{horizontal scroll position}, which is a number, never
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1531 less than zero. It specifies how far to shift the contents left.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1532 Shifting the window contents left generally makes all or part of some
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1533 characters disappear off the left, and all or part of some other
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1534 characters appear at the right. The usual value is zero.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1535
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1536 The horizontal scroll position is measured in units of the normal
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1537 character width, which is the width of space in the default font. Thus,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1538 if the value is 5, that means the window contents are scrolled left by 5
36352
a2d558c2b733 (Horizontal Scrolling): Remove doubled `the'.
Gerd Moellmann <gerd@gnu.org>
parents: 34749
diff changeset
1539 times the normal character width. How many characters actually
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1540 disappear off to the left depends on their width, and could vary from
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1541 line to line.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1542
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1543 Because we read from side to side in the ``inner loop'', and from top
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1544 to bottom in the ``outer loop'', the effect of horizontal scrolling is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1545 not like that of textual or vertical scrolling. Textual scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1546 involves selection of a portion of text to display, and vertical
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1547 scrolling moves the window contents contiguously; but horizontal
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1548 scrolling causes part of @emph{each line} to go off screen.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 Usually, no horizontal scrolling is in effect; then the leftmost
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 column is at the left edge of the window. In this state, scrolling to
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1552 the right is meaningless, since there is no data to the left of the edge
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1553 to be revealed by it; so this is not allowed. Scrolling to the left is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1554 allowed; it scrolls the first columns of text off the edge of the window
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1555 and can reveal additional columns on the right that were truncated
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1556 before. Once a window has a nonzero amount of leftward horizontal
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1557 scrolling, you can scroll it back to the right, but only so far as to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1558 reduce the net horizontal scroll to zero. There is no limit to how far
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1559 left you can scroll, but eventually all the text will disappear off the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1560 left edge.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561
43665
717f4f88556c (Horizontal Scrolling): Rename automatic-hscrolling to auto-hscroll-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 43257
diff changeset
1562 @vindex auto-hscroll-mode
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1563 In Emacs 21, redisplay automatically alters the horizontal scrolling
34749
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1564 of a window as necessary to ensure that point is always visible, if
43665
717f4f88556c (Horizontal Scrolling): Rename automatic-hscrolling to auto-hscroll-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 43257
diff changeset
1565 @code{auto-hscroll-mode} is set. However, you can still set the
34749
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1566 horizontal scrolling value explicitly. The value you specify serves as
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1567 a lower bound for automatic scrolling, i.e. automatic scrolling
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1568 will not scroll a window to a column less than the specified one.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1569
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1570 @deffn Command scroll-left &optional count
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571 This function scrolls the selected window @var{count} columns to the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1572 left (or to the right if @var{count} is negative). The default
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1573 for @var{count} is the window width, minus 2.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1574
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1575 The return value is the total amount of leftward horizontal scrolling in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1576 effect after the change---just like the value returned by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1577 @code{window-hscroll} (below).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1580 @deffn Command scroll-right &optional count
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581 This function scrolls the selected window @var{count} columns to the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1582 right (or to the left if @var{count} is negative). The default
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1583 for @var{count} is the window width, minus 2.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1584
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1585 The return value is the total amount of leftward horizontal scrolling in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1586 effect after the change---just like the value returned by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1587 @code{window-hscroll} (below).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 Once you scroll a window as far right as it can go, back to its normal
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 position where the total leftward scrolling is zero, attempts to scroll
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 any farther right have no effect.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594 @defun window-hscroll &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1595 This function returns the total leftward horizontal scrolling of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1596 @var{window}---the number of columns by which the text in @var{window}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1597 is scrolled left past the left margin.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1598
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599 The value is never negative. It is zero when no horizontal scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1600 has been done in @var{window} (which is usually the case).
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1601
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602 If @var{window} is @code{nil}, the selected window is used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606 (window-hscroll)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 @result{} 0
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 (scroll-left 5)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611 @result{} 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614 (window-hscroll)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 @result{} 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 @defun set-window-hscroll window columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 This function sets the number of columns from the left margin that
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1622 @var{window} is scrolled from the value of @var{columns}. The argument
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 @var{columns} should be zero or positive; if not, it is taken as zero.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1624 Fractional values of @var{columns} are not supported at present.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625
45679
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1626 Note that @code{set-window-hscroll} may appear not to work if you test
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1627 it by evaluating a call with @kbd{M-:} in a simple way. What happens
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1628 is that the function sets the horizontal scroll value and returns, but
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1629 then redisplay adjusts the horizontal scrolling to make point visible,
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1630 and this overrides what the function did. You can observe the
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1631 function's effect if you call it while point is sufficiently far from
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1632 the left margin that it will remain visible.
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1633
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 The value returned is @var{columns}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 (set-window-hscroll (selected-window) 10)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639 @result{} 10
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1643
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644 Here is how you can determine whether a given position @var{position}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645 is off the screen due to horizontal scrolling:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1646
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1647 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1648 @group
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1649 (defun hscroll-on-screen (window position)
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1650 (save-excursion
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1651 (goto-char position)
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1652 (and
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1653 (>= (- (current-column) (window-hscroll window)) 0)
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1654 (< (- (current-column) (window-hscroll window))
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1655 (window-width window)))))
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659 @node Size of Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660 @section The Size of a Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 @cindex window size
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1662 @cindex size of window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1663
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1664 An Emacs window is rectangular, and its size information consists of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1665 the height (the number of lines) and the width (the number of character
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1666 positions in each line). The mode line is included in the height. But
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1667 the width does not count the scroll bar or the column of @samp{|}
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1668 characters that separates side-by-side windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1669
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670 The following three functions return size information about a window:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1671
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1672 @defun window-height &optional window
42819
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1673 This function returns the number of lines in @var{window}, including
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1674 its mode line and header line, if any. If @var{window} fills its
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1675 entire frame except for the echo area, and there is no tool bar, this
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1676 is typically one less than the value of @code{frame-height} on that
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1677 frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1678
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1679 If @var{window} is @code{nil}, the function uses the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 (window-height)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1684 @result{} 23
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687 (split-window-vertically)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1688 @result{} #<window 4 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1689 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1690 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691 (window-height)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 @result{} 11
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1695 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696
42819
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1697 @tindex window-body-height
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1698 @defun window-body-height &optional window
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1699 Like @code{window-height} but the value does not include the
42819
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1700 mode line (if any) or the header line (if any).
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1701 @end defun
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1702
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1703 @defun window-width &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704 This function returns the number of columns in @var{window}. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705 @var{window} fills its entire frame, this is the same as the value of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706 @code{frame-width} on that frame. The width does not include the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707 window's scroll bar or the column of @samp{|} characters that separates
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1708 side-by-side windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1709
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1710 If @var{window} is @code{nil}, the function uses the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1711
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1712 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1714 (window-width)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1715 @result{} 80
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1716 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 @defun window-edges &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 This function returns a list of the edge coordinates of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722 If @var{window} is @code{nil}, the selected window is used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 The order of the list is @code{(@var{left} @var{top} @var{right}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 the frame. The element @var{right} of the value is one more than the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 rightmost column used by @var{window}, and @var{bottom} is one more than
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 the bottommost row used by @var{window} and its mode-line.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1730 If a window has a scroll bar, the right edge value includes the width of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1731 the scroll bar. Otherwise, if the window has a neighbor on the right,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1732 its right edge value includes the width of the separator line between
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1733 the window and that neighbor. Since the width of the window does not
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1734 include this separator, the width does not usually equal the difference
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1735 between the right and left edges.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1737 Here is the result obtained on a typical 24-line terminal with just one
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1738 window:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1739
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1740 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1741 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742 (window-edges (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1743 @result{} (0 0 80 23)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1744 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1745 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1746
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1747 @noindent
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1748 The bottom edge is at line 23 because the last line is the echo area.
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1749
13275
33bdb63a2c59 Minor fix.
Richard M. Stallman <rms@gnu.org>
parents: 12673
diff changeset
1750 If @var{window} is at the upper left corner of its frame, then
33bdb63a2c59 Minor fix.
Richard M. Stallman <rms@gnu.org>
parents: 12673
diff changeset
1751 @var{bottom} is the same as the value of @code{(window-height)},
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1752 @var{right} is almost the same as the value of @code{(window-width)},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1753 and @var{top} and @var{left} are zero. For example, the edges of the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1754 following window are @w{@samp{0 0 8 5}}. Assuming that the frame has
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1755 more than 8 columns, the last column of the window (column 7) holds a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1756 border rather than text. The last row (row 4) holds the mode line,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1757 shown here with @samp{xxxxxxxxx}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1758
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760 @group
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1761 0
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 _______
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1763 0 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1764 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1765 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1766 | |
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 xxxxxxxxx 4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1769 7
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 In the following example, let's suppose that the frame is 7
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1775 and the edges of the right window are @w{@samp{4 0 8 3}}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1776
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1778 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 ___ ___
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1780 | | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1781 | | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1782 xxxxxxxxx
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1784 0 34 7
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1785 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1786 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1787 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1788
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 @node Resizing Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790 @section Changing the Size of a Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1791 @cindex window resizing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1792 @cindex changing window size
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1793 @cindex window size, changing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1795 The window size functions fall into two classes: high-level commands
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1796 that change the size of windows and low-level functions that access
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 window size. Emacs does not permit overlapping windows or gaps between
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 windows, so resizing one window affects other windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1799
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1800 @deffn Command enlarge-window size &optional horizontal
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1801 This function makes the selected window @var{size} lines taller,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1802 stealing lines from neighboring windows. It takes the lines from one
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1803 window at a time until that window is used up, then takes from another.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1804 If a window from which lines are stolen shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805 @code{window-min-height} lines, that window disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1806
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 If @var{horizontal} is non-@code{nil}, this function makes
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808 @var{window} wider by @var{size} columns, stealing columns instead of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1809 lines. If a window from which columns are stolen shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1810 @code{window-min-width} columns, that window disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1811
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1812 If the requested size would exceed that of the window's frame, then the
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1813 function makes the window occupy the entire height (or width) of the
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1814 frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1816 If there are various other windows from which lines or columns can be
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1817 stolen, and some of them specify fixed size (using
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1818 @code{window-size-fixed}, see below), they are left untouched while
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1819 other windows are ``robbed.'' If it would be necessary to alter the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1820 size of a fixed-size window, @code{enlarge-window} gets an error
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1821 instead.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1822
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1823 If @var{size} is negative, this function shrinks the window by
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1824 @minus{}@var{size} lines or columns. If that makes the window smaller
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1825 than the minimum size (@code{window-min-height} and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826 @code{window-min-width}), @code{enlarge-window} deletes the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1828 @code{enlarge-window} returns @code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 @deffn Command enlarge-window-horizontally columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 This function makes the selected window @var{columns} wider.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833 It could be defined as follows:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1834
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 (defun enlarge-window-horizontally (columns)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 (enlarge-window columns t))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 @deffn Command shrink-window size &optional horizontal
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844 This function is like @code{enlarge-window} but negates the argument
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 @var{size}, making the selected window smaller by giving lines (or
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846 columns) to the other windows. If the window shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847 @code{window-min-height} or @code{window-min-width}, then it disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850 lines or columns.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853 @deffn Command shrink-window-horizontally columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 This function makes the selected window @var{columns} narrower.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 It could be defined as follows:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1859 (defun shrink-window-horizontally (columns)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1860 (shrink-window columns t))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1861 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1865 @deffn Command shrink-window-if-larger-than-buffer &optional window
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1866 This command shrinks @var{window} to be as small as possible while still
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1867 showing the full contents of its buffer---but not less than
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1868 @code{window-min-height} lines. If @var{window} is not given,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1869 it defaults to the selected window.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1870
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1871 However, the command does nothing if the window is already too small to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1872 display the whole text of the buffer, or if part of the contents are
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1873 currently scrolled off screen, or if the window is not the full width of
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1874 its frame, or if the window is the only window in its frame.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1875 @end deffn
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1876
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1877 @tindex window-size-fixed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1878 @defvar window-size-fixed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1879 If this variable is non-@code{nil}, in any given buffer,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1880 then the size of any window displaying the buffer remains fixed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1881 unless you explicitly change it or Emacs has no other choice.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1882 (This feature is new in Emacs 21.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1883
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1884 If the value is @code{height}, then only the window's height is fixed;
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1885 if the value is @code{width}, then only the window's width is fixed.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1886 Any other non-@code{nil} value fixes both the width and the height.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1887
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1888 The usual way to use this variable is to give it a buffer-local value in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1889 a particular buffer. That way, the windows (but usually there is only
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1890 one) displaying that buffer have fixed size.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1891
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1892 Explicit size-change functions such as @code{enlarge-window}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1893 get an error if they would have to change a window size which is fixed.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1894 Therefore, when you want to change the size of such a window,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1895 you should bind @code{window-size-fixed} to @code{nil}, like this:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1896
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1897 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1898 (let ((window-size-fixed nil))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1899 (enlarge-window 10))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1900 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1901
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1902 Note that changing the frame size will change the size of a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1903 fixed-size window, if there is no other alternative.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1904 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1905
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1906 @cindex minimum window size
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1907 The following two variables constrain the window-structure-changing
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908 functions to a minimum height and width.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1909
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1910 @defopt window-min-height
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1911 The value of this variable determines how short a window may become
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1912 before it is automatically deleted. Making a window smaller than
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1913 @code{window-min-height} automatically deletes it, and no window may
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1914 be created shorter than this. The default value is 4.
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1915
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1916 The absolute minimum window height is one; actions that change window
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1917 sizes reset this variable to one if it is less than one.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1918 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1920 @defopt window-min-width
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1921 The value of this variable determines how narrow a window may become
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1922 before it is automatically deleted. Making a window smaller than
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1923 @code{window-min-width} automatically deletes it, and no window may be
42868
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1924 created narrower than this. The default value is 10.
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1925
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1926 The absolute minimum window width is two; actions that change window
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1927 sizes reset this variable to two if it is less than two.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1928 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1929
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1930 @node Coordinates and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1931 @section Coordinates and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1932
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1933 This section describes how to relate screen coordinates to windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1934
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1935 @defun window-at x y &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1936 This function returns the window containing the specified cursor
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1937 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1938 are measured in characters and count from the top left corner of the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1939 frame. If they are out of range, @code{window-at} returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 If you omit @var{frame}, the selected frame is used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944 @defun coordinates-in-window-p coordinates window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 This function checks whether a particular frame position falls within
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946 the window @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1947
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1948 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1949 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1950 characters, and count from the top left corner of the screen or frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1952 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1953 if the coordinates are inside @var{window}. The value also indicates
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1954 what part of the window the position is in, as follows:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1955
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1956 @table @code
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1957 @item (@var{relx} . @var{rely})
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1958 The coordinates are inside @var{window}. The numbers @var{relx} and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 @var{rely} are the equivalent window-relative coordinates for the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 specified position, counting from 0 at the top left corner of the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961 window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 @item mode-line
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964 The coordinates are in the mode line of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1965
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1966 @item header-line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1967 The coordinates are in the header line of @var{window}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1968
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1969 @item vertical-line
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 The coordinates are in the vertical line between @var{window} and its
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1971 neighbor to the right. This value occurs only if the window doesn't
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 have a scroll bar; positions in a scroll bar are considered outside the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1973 window for these purposes.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 @item nil
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976 The coordinates are not in any part of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 @end table
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1978
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1979 The function @code{coordinates-in-window-p} does not require a frame as
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 argument because it always uses the frame that @var{window} is on.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983 @node Window Configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 @section Window Configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 @cindex window configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 @cindex saving window information
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1988 A @dfn{window configuration} records the entire layout of one
45583
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1989 frame---all windows, their sizes, which buffers they contain, what
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1990 part of each buffer is displayed, and the values of point and the
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1991 mark. It also includes the values of @code{window-min-height},
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1992 @code{window-min-width} and @code{minibuffer-scroll-window}. An
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1993 exception is made for point in the selected window for the current
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1994 buffer; its value is not saved in the window configuration.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995
45583
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1996 You can bring back an entire previous layout by restoring a window
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1997 configuration previously saved. If you want to record all frames
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1998 instead of just one, use a frame configuration instead of a window
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
1999 configuration. @xref{Frame Configurations}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2001 @defun current-window-configuration &optional frame
45583
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
2002 This function returns a new object representing @var{frame}'s current
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
2003 window configuration. If @var{frame} is omitted, the selected frame
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
2004 is used.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2006
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 @defun set-window-configuration configuration
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2008 This function restores the configuration of windows and buffers as
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2009 specified by @var{configuration}, for the frame that @var{configuration}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2010 was created for.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2011
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2012 The argument @var{configuration} must be a value that was previously
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2013 returned by @code{current-window-configuration}. This configuration is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2014 restored in the frame from which @var{configuration} was made, whether
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2015 that frame is selected or not. This always counts as a window size
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2016 change and triggers execution of the @code{window-size-change-functions}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2017 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2018 know how to tell whether the new configuration actually differs from the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2019 old one.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2020
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2021 If the frame which @var{configuration} was saved from is dead, all this
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2022 function does is restore the three variables @code{window-min-height},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2023 @code{window-min-width} and @code{minibuffer-scroll-window}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2024
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025 Here is a way of using this function to get the same effect
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 as @code{save-window-excursion}:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2028 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2029 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 (let ((config (current-window-configuration)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031 (unwind-protect
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032 (progn (split-window-vertically nil)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2033 @dots{})
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2034 (set-window-configuration config)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2035 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2036 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2037 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039 @defspec save-window-excursion forms@dots{}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2040 This special form records the window configuration, executes @var{forms}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2041 in sequence, then restores the earlier window configuration. The window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042 configuration includes the value of point and the portion of the buffer
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2043 that is visible. It also includes the choice of selected window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044 However, it does not include the value of point in the current buffer;
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2045 use @code{save-excursion} also, if you wish to preserve that.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2047 Don't use this construct when @code{save-selected-window} is all you need.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2048
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2049 Exit from @code{save-window-excursion} always triggers execution of the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2050 @code{window-size-change-functions}. (It doesn't know how to tell
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2051 whether the restored configuration actually differs from the one in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2052 effect at the end of the @var{forms}.)
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2053
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2054 The return value is the value of the final form in @var{forms}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2055 For example:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2056
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2057 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2058 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2059 (split-window)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060 @result{} #<window 25 on control.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2061 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2062 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2063 (setq w (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2064 @result{} #<window 19 on control.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2065 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2066 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2067 (save-window-excursion
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 (delete-other-windows w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069 (switch-to-buffer "foo")
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070 'do-something)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071 @result{} do-something
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2072 ;; @r{The screen is now split again.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 @end defspec
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 @defun window-configuration-p object
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078 This function returns @code{t} if @var{object} is a window configuration.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2081 @defun compare-window-configurations config1 config2
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2082 This function compares two window configurations as regards the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2083 structure of windows, but ignores the values of point and mark and the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2084 saved scrolling positions---it can return @code{t} even if those
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2085 aspects differ.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2086
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2087 The function @code{equal} can also compare two window configurations; it
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2088 regards configurations as unequal if they differ in any respect, even a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2089 saved point or mark.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2090 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2091
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092 Primitives to look inside of window configurations would make sense,
47687
054a4d4af618 (Window Configurations): Refer to winner.el as example.
Richard M. Stallman <rms@gnu.org>
parents: 45679
diff changeset
2093 but none are implemented. It is not clear they are useful enough to
054a4d4af618 (Window Configurations): Refer to winner.el as example.
Richard M. Stallman <rms@gnu.org>
parents: 45679
diff changeset
2094 be worth implementing. See the file @file{winner.el} for some more
054a4d4af618 (Window Configurations): Refer to winner.el as example.
Richard M. Stallman <rms@gnu.org>
parents: 45679
diff changeset
2095 operations on windows configurations.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2096
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2097 @node Window Hooks
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2098 @section Hooks for Window Scrolling and Changes
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2099
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2100 This section describes how a Lisp program can take action whenever a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2101 window displays a different part of its buffer or a different buffer.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2102 There are three actions that can change this: scrolling the window,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2103 switching buffers in the window, and changing the size of the window.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2104 The first two actions run @code{window-scroll-functions}; the last runs
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2105 @code{window-size-change-functions}. The paradigmatic use of these
50475
b65aa1d740eb Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents: 49961
diff changeset
2106 hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2107
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2108 @defvar window-scroll-functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2109 This variable holds a list of functions that Emacs should call before
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2110 redisplaying a window with scrolling. It is not a normal hook, because
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2111 each function is called with two arguments: the window, and its new
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2112 display-start position.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2113
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2114 Displaying a different buffer in the window also runs these functions.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2115
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2116 These functions must be careful in using @code{window-end}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2117 (@pxref{Window Start}); if you need an up-to-date value, you must use
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2118 the @var{update} argument to ensure you get it.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2119 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2120
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2121 @defvar window-size-change-functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2122 This variable holds a list of functions to be called if the size of any
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2123 window changes for any reason. The functions are called just once per
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2124 redisplay, and just once for each frame on which size changes have
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2125 occurred.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2126
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2127 Each function receives the frame as its sole argument. There is no
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2128 direct way to find out which windows on that frame have changed size, or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2129 precisely how. However, if a size-change function records, at each
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2130 call, the existing windows and their sizes, it can also compare the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2131 present sizes and the previous sizes.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2132
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2133 Creating or deleting windows counts as a size change, and therefore
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2134 causes these functions to be called. Changing the frame size also
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2135 counts, because it changes the sizes of the existing windows.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2136
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2137 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2138 Configurations}) in these functions, because that always counts as a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2139 size change, and it would cause these functions to be called over and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2140 over. In most cases, @code{save-selected-window} (@pxref{Selecting
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2141 Windows}) is what you need here.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2142 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2143
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2144 @defvar redisplay-end-trigger-functions
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2145 This abnormal hook is run whenever redisplay in a window uses text that
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2146 extends past a specified end trigger position. You set the end trigger
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2147 position with the function @code{set-window-redisplay-end-trigger}. The
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2148 functions are called with two arguments: the window, and the end trigger
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2149 position. Storing @code{nil} for the end trigger position turns off the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2150 feature, and the trigger value is automatically reset to @code{nil} just
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2151 after the hook is run.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2152 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2153
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2154 @defun set-window-redisplay-end-trigger window position
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2155 This function sets @var{window}'s end trigger position at
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2156 @var{position}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2157 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2158
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2159 @defun window-redisplay-end-trigger &optional window
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2160 This function returns @var{window}'s current end trigger position.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2161 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2162
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2163 @defvar window-configuration-change-hook
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2164 A normal hook that is run every time you change the window configuration
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2165 of an existing frame. This includes splitting or deleting windows,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2166 changing the sizes of windows, or displaying a different buffer in a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2167 window. The frame whose window configuration has changed is the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2168 selected frame when this hook runs.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2169 @end defvar