annotate lispref/windows.texi @ 52635:9963e9da5850

(quote_file_name): Print the result instead of returning it. Fix the return type accordingly. (main): Under --eval, don't fail if left with additional arguments after decoding options. Quote file names.
author Eli Zaretskii <eliz@gnu.org>
date Sun, 28 Sep 2003 08:24:56 +0000
parents 695cf19ef79e
children 2ff062ff0422 375f2633d815
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
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
404 @defun select-window window &optional norecord
6564
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
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
409 Normally @var{window}'s selected buffer is moved to the front of the
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
410 buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
411 order is unchanged.
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
412
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 The return value is @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 (setq w (next-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 (select-window w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @result{} #<window 65 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
424 @defmac save-selected-window forms@dots{}
51997
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
425 This macro records the selected window of eac frame, executes
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
426 @var{forms} in sequence, then restores the earlier selected windows.
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
51997
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
428 This macro does not save or restore anything about the sizes,
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
429 arrangement or contents of windows; therefore, if the @var{forms}
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
430 change them, the change persists. If the previously selected window
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
431 of some frame is no longer live at the time of exit from this form,
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
432 that frame's selected window is left alone.
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
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
435 @defmac with-selected-window window forms@dots{}
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
436 This macro selects @var{window} (without changing the buffer list),
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
437 executes @var{forms} in sequence, then restores the previously
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
438 selected window (unless that window is no longer alive). It is similar
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
439 to @code{save-selected-window} except that it explicitly selects
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
440 @var{window} and that it does not alter the buffer list sequence.
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
441 @end defmac
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
442
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @cindex finding windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 The following functions choose one of the windows on the screen,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 offering various criteria for the choice.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @defun get-lru-window &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 This function returns the window least recently ``used'' (that is,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 selected). The selected window is always the most recently used window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 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
452 only window. A newly created window becomes the least recently used
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 window until it is selected. A minibuffer window is never a candidate.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
455 The argument @var{frame} controls which windows are considered.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 If it is @code{nil}, consider windows on the selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 If it is @code{t}, consider windows on all frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 If it is @code{visible}, consider windows on all visible frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
465 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
466 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 If it is a frame, consider windows on that frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @defun get-largest-window &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 This function returns the window with the largest area (height times
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 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
474 with the most lines. A minibuffer window is never a candidate.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 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
477 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
478 following section), starting from the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
480 The argument @var{frame} controls which set of windows to
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
481 consider. See @code{get-lru-window}, above.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
39207
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
484 @cindex window that satisfies a predicate
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
485 @cindex conditional selection of windows
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
486 @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
487 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
488 through all visible windows using @code{walk-windows} (@pxref{Cyclic
51704
f954442d2253 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
489 Window Ordering}), calling @var{predicate} on each one of them
39207
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
490 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
491 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
492 that never happens, it returns @var{default}.
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
493
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
494 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
495 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
496 @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
497 @end defun
5fb1514f98a5 (Selecting Windows): Document some-window.
Eli Zaretskii <eliz@gnu.org>
parents: 38380
diff changeset
498
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @node Cyclic Window Ordering
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @comment node-name, next, previous, up
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @section Cyclic Ordering of Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @cindex cyclic ordering of windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @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
504 @cindex window ordering, cyclic
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 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
507 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
508 specific cyclic order. For any given configuration of windows, this
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 order never varies. It is called the @dfn{cyclic ordering of windows}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 This ordering generally goes from top to bottom, and from left to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 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
513 order in which the windows were split.
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 If the first split was vertical (into windows one above each other),
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 and then the subwindows were split horizontally, then the ordering is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 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
518 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
519 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
520 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
521 the order is left to right, or top to bottom.
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 @defun next-window &optional window minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @cindex minibuffer window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 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
526 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
527 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
528 window visible, then this function returns @var{window}. If omitted,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @var{window} defaults to the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 The value of the argument @var{minibuf} determines whether the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 minibuffer is included in the window order. Normally, when
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 @var{minibuf} is @code{nil}, the minibuffer is included if it is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 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
535 window is active while the minibuffer is in use. @xref{Minibuffers}.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 minibuffer window even if it is not active.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 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
541 window is not included even if it is active.
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 The argument @var{all-frames} specifies which frames to consider. Here
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 are the possible values and their meanings:
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 @table @asis
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @item @code{nil}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 Consider all the windows in @var{window}'s frame, plus the minibuffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 used by that frame even if it lies in some other frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @item @code{t}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 Consider all windows in all existing frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @item @code{visible}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 Consider all windows in all visible frames. (To get useful results, you
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 must ensure @var{window} is in a visible frame.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557
12099
66bde18bb391 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12098
diff changeset
558 @item 0
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
559 Consider all windows in all visible or iconified frames.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
560
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @item anything else
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 Consider precisely the windows in @var{window}'s frame, and no others.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @end table
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
565 This example assumes there are two windows, both displaying the
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 buffer @samp{windows.texi}:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @example
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 (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 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 (next-window (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @result{} #<window 52 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 (next-window (next-window (selected-window)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @result{} #<window 56 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @defun previous-window &optional window minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 This function returns the window preceding @var{window} in the cyclic
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 ordering of windows. The other arguments specify which windows to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 include in the cycle, as in @code{next-window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
590 @deffn Command other-window count &optional all-frames
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 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
592 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
593 windows in the cycle, rather than forward. It returns @code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
595 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
596 @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
597 is always effectively @code{nil}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
598
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 In an interactive call, @var{count} is the numeric prefix argument.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @defun walk-windows proc &optional minibuf all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 This function cycles through all windows, calling @code{proc}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 once for each window with the window as its sole argument.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 The optional arguments @var{minibuf} and @var{all-frames} specify the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 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
609 for details.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611
33656
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
612 @defun window-list &optional frame minibuf window
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
613 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
614 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
615 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
616 omitted, the selected window is used instead.
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
617
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
618 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
619 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
620 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
621 @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
622 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
623 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
624 included, whether or not it is active.
33826
a39402e633cd Fix markup.
Dave Love <fx@gnu.org>
parents: 33656
diff changeset
625 @end defun
33656
f17374b3bc22 Add description of function window-list.
Gerd Moellmann <gerd@gnu.org>
parents: 30665
diff changeset
626
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @node Buffers and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @section Buffers and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @cindex examining windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @cindex windows, controlling precisely
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @cindex buffers, controlled in windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 This section describes low-level functions to examine windows or to
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 display buffers in windows in a precisely controlled fashion.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @iftex
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 See the following section for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
638 @ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @xref{Displaying Buffers}, for
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
640 @end ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 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
642 The functions described there are easier to use than these, but they
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 employ heuristics in choosing or creating a window; use these functions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 when you need complete control.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645
52151
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
646 @defun set-window-buffer window buffer-or-name &optional keep-margins
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 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
648 contents. It returns @code{nil}. This is the fundamental primitive
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
649 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
650 of doing that call this function.
6564
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 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 (set-window-buffer (selected-window) "foo")
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @result{} nil
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @end example
52151
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
658
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
659 Normally, displaying @var{buffer} in @var{window} resets the window's
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
660 fringe widths and position based on the local variables of @var{buffer}.
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
661 However, if @var{keep-margins} is non-@code{nil}, the fringe widths and
eddd7191f683 (Buffers and Windows): set-window-buffer has new arg.
Richard M. Stallman <rms@gnu.org>
parents: 51997
diff changeset
662 position of @var{window} remain unchanged. @xref{Fringes}.
6564
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 window-buffer &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 This function returns the buffer that @var{window} is displaying. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @var{window} is omitted, this function returns the buffer for the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 (window-buffer)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @result{} #<buffer windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 @defun get-buffer-window buffer-or-name &optional all-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 This function returns a window currently displaying
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 @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
681 several such windows, then the function returns the first one in the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 cyclic ordering of windows, starting from the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @xref{Cyclic Window Ordering}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 The argument @var{all-frames} controls which windows to consider.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @itemize @bullet
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 If it is @code{nil}, consider windows on the selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 If it is @code{t}, consider windows on all frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 If it is @code{visible}, consider windows on all visible frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
695 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
696 @item
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 If it is a frame, consider windows on that frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @end itemize
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
701 @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
702 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
703 @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
704
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
705 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
706 @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
707 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
708 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
709 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
710
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
711 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
712
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
713 @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
714 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
715 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
716 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
717 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
718 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
719 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
720 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
721 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
722 @item
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
723 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
724 @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
725 @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
726
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
727 @defvar buffer-display-time
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
728 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
729 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
730 @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
731 @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
732 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
733 with the value @code{nil}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
734 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
735
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @node Displaying Buffers
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @section Displaying Buffers in Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @cindex switching to a buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 @cindex displaying a buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 In this section we describe convenient functions that choose a window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 automatically and use it to display a specified buffer. These functions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 can also split an existing window in certain circumstances. We also
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 describe variables that parameterize the heuristics used for choosing a
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @iftex
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 See the preceding section for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
749 @ifnottex
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @xref{Buffers and Windows}, for
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
751 @end ifnottex
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
752 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
753 functions work by calling @code{set-window-buffer}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 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
756 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
757 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
758 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
759 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
760 Buffer}), which designate buffers as current for programmed access
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
761 without affecting the display of buffers in windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @deffn Command switch-to-buffer buffer-or-name &optional norecord
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 This function makes @var{buffer-or-name} the current buffer, and also
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 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
766 see the buffer and subsequent keyboard commands will apply to it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 the current buffer but does not display it in the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @xref{Current Buffer}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
771 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
772 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
773 set according to the variable @code{default-major-mode}. @xref{Auto
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
774 Major Mode}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
776 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
777 (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
778 list). This affects the operation of @code{other-buffer}. However, if
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 @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
780 List}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 The @code{switch-to-buffer} function is often used interactively, as
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 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
784 returns the buffer that it switched to.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
787 @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
788 This function makes @var{buffer-or-name} the current buffer and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 displays it in a window not currently selected. It then selects that
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 window. The handling of the buffer is the same as in
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 @code{switch-to-buffer}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
793 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
794 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
795 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
796 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
797 display it in as well.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
798
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
799 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
800 unless @var{norecord} is non-@code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
803 @defun pop-to-buffer buffer-or-name &optional other-window norecord
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 This function makes @var{buffer-or-name} the current buffer and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 switches to it in some window, preferably not the window previously
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 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
807 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
808
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 If the variable @code{pop-up-frames} is non-@code{nil},
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @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
811 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
812 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
813 frame and displays the buffer in it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 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
816 operates entirely within the selected frame. (If the selected frame has
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 just a minibuffer, @code{pop-to-buffer} operates within the most
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 recently selected frame that was not just a minibuffer.)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 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
821 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
822 window. For details, see @ref{Choosing Window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 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
825 creates another window even if @var{buffer-or-name} is already visible
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 in the selected window. Thus @var{buffer-or-name} could end up
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 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
828 already displayed in the selected window and @var{other-window} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @code{nil}, then the selected window is considered sufficient display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 for @var{buffer-or-name}, so that nothing needs to be done.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
832 All the variables that affect @code{display-buffer} affect
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
833 @code{pop-to-buffer} as well. @xref{Choosing Window}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
834
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 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
836 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
837 buffer is set according to the variable @code{default-major-mode}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11510
diff changeset
838 @xref{Auto Major Mode}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
839
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
840 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
841 unless @var{norecord} is non-@code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
844 @deffn Command replace-buffer-in-windows buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
845 This function replaces @var{buffer} with some other buffer in all
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
846 windows displaying it. The other buffer used is chosen with
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
847 @code{other-buffer}. In the usual applications of this function, you
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
848 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
849 @var{buffer} is no longer displayed.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
850
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
851 This function returns @code{nil}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
852 @end deffn
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
853
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 @node Choosing Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @section Choosing a Window for Display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
857 This section describes the basic facility that chooses a window to
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 display a buffer in---@code{display-buffer}. All the higher-level
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 functions and commands use this subroutine. Here we describe how to use
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @code{display-buffer} and how to customize it.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
862 @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
863 This command makes @var{buffer-or-name} appear in some window, like
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 @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
865 make the buffer current. The identity of the selected window is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 unaltered by this function.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 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
869 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
870 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
871 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
872 already being displayed in any window, that is good enough, so this
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 function does nothing.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @code{display-buffer} returns the window chosen to display
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @var{buffer-or-name}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
878 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
879 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
880 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
881 @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
882 values of @var{frame}:
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
883
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
884 @itemize @bullet
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
885 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
886 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
887 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
888 If it is @code{t}, consider windows on all frames.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
889 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
890 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
891 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
892 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
893 @item
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
894 If it is a frame, consider windows on that frame.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
895 @end itemize
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
896
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 Precisely how @code{display-buffer} finds or creates a window depends on
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 the variables described below.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900
30665
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
901 @defopt display-buffer-reuse-frames
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
902 If this variable is non-@code{nil}, @code{display-buffer} searches
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
903 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
904 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
905 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
906 not already displayed, or if @code{display-buffer-reuse-frames} is
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
907 @code{nil}, @code{display-buffer}'s behavior is determined by other
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
908 variables, described below.
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
909 @end defopt
6f2c9914b5b0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27374
diff changeset
910
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 @defopt pop-up-windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 This variable controls whether @code{display-buffer} makes new windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 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
914 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
915 split the single window, but uses it whole.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 @defopt split-height-threshold
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 This variable determines when @code{display-buffer} may split a window,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 if there are multiple windows. @code{display-buffer} always splits the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 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
922 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
923 @code{pop-up-windows} is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925
34269
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
926 @defopt even-window-heights
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
927 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
928 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
929 beneath another existing window. If @code{even-window-heights} is
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
930 @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
931 @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
932 will be left alone.
34307
91a288b94484 close @defopt.
Dave Love <fx@gnu.org>
parents: 34269
diff changeset
933 @end defopt
34269
a50ccd431a27 Add event-window-heights.
Gerd Moellmann <gerd@gnu.org>
parents: 33992
diff changeset
934
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 @defopt pop-up-frames
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 This variable controls whether @code{display-buffer} makes new frames.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 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
939 window already displaying the desired buffer, on any visible frame. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 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
941 The variables @code{pop-up-windows} and @code{split-height-threshold} do
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 not matter if @code{pop-up-frames} is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 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
945 splits a window or reuses one.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @xref{Frames}, for more information.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 @defvar pop-up-frame-function
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 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
953 is non-@code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 Its value should be a function of no arguments. When
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @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
957 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
958 variable is a function that creates a frame using parameters from
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 @code{pop-up-frame-alist}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
962 @defopt pop-up-frame-alist
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 This variable holds an alist specifying frame parameters used when
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 more information about frame parameters.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
966 @end defopt
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
968 @defopt special-display-buffer-names
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
969 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
970 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
971 buffer specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
972
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
973 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
974
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
975 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
976 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
977 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
978 @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
979 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
980 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
981 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
982
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
983 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
984
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
985 @example
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
986 (("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
987 @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
988
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
989 @noindent
64f6bc336d1b Give example of using special-display-buffer-names to specify frame parameters.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
990 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
991 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
992 @end defopt
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
993
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
994 @defopt special-display-regexps
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
995 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
996 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
997 expressions in this list, @code{display-buffer} handles the buffer
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
998 specially.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
999
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1000 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
1001
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1002 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
1003 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
1004 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
1005 @end defopt
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1006
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1007 @defvar special-display-function
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1008 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
1009 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
1010 which it is displayed.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1011
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1012 The default value of this variable is
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1013 @code{special-display-popup-frame}.
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1014 @end defvar
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1015
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1016 @defun special-display-popup-frame buffer &rest args
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1017 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
1018 @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
1019 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
1020 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
1021
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1022 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
1023 frame.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1024
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1025 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
1026 @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
1027 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
1028 @var{args})} as additional arguments.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1029
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1030 This function always uses an existing window displaying @var{buffer},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1031 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
1032 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
1033 presumably the window was previously made by this function.
7082
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1034 @end defun
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1035
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1036 @defopt special-display-frame-alist
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1037 This variable holds frame parameters for
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1038 @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
1039 @end defopt
70b62e9d773b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6564
diff changeset
1040
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1041 @defopt same-window-buffer-names
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1042 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
1043 selected window. If the buffer's name is in this list,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1044 @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
1045 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
1046 @end defopt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1047
12673
4d6b7909a0ec Use defopt for same-window-buffer-names and same-window-regexps.
Richard M. Stallman <rms@gnu.org>
parents: 12596
diff changeset
1048 @defopt same-window-regexps
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1049 A list of regular expressions that specify buffers that should be
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1050 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
1051 the regular expressions in this list, @code{display-buffer} handles the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1052 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
1053 @end defopt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1054
6564
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 @defvar display-buffer-function
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 This variable is the most flexible way to customize the behavior of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @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
1059 that @code{display-buffer} calls to do the work. The function should
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 accept two arguments, the same two arguments that @code{display-buffer}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 received. It should choose or create a window, display the specified
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 buffer, and then return the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 This hook takes precedence over all the other options and hooks
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 described above.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @cindex dedicated window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 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
1071 @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
1072 other buffer.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 @defun window-dedicated-p window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 This function returns @code{t} if @var{window} is marked as dedicated;
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 otherwise @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 @defun set-window-dedicated-p window flag
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 This function marks @var{window} as dedicated if @var{flag} is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 non-@code{nil}, and nondedicated otherwise.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @node Window Point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 @section Windows and Point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 @cindex window position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 @cindex window point
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @cindex position in window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 @cindex point in window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 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
1092 point in other windows displaying the same buffer. This makes it useful
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 to have multiple windows showing one buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095 @itemize @bullet
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 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
1098 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
1099 window opened on the buffer if such a window exists.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1102 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
1103 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
1104 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
1105 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
1106 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
1107 the other windows are stored in those windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 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
1111 point and the buffer's point always move together; they remain equal.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @item
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 @xref{Positions}, for more details on buffer positions.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 @end itemize
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 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
1118 when the user switches to another buffer, the cursor jumps to the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 position of point in that buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1121 @defun window-point &optional window
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 This function returns the current position of point in @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 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
1124 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
1125 @code{nil}, the selected window is used.
6564
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 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
1128 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
1129
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 Strictly speaking, it would be more correct to return the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 ``top-level'' value of point, outside of any @code{save-excursion}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 forms. But that value is hard to find.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @defun set-window-point window position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 This function positions point in @var{window} at position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @var{position} in @var{window}'s buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @node Window Start
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 @section The Window Start Position
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 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
1144 that specifies where in the buffer display should start. This position
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 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
1146 @dfn{start}). The character after this position is the one that appears
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 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
1148 inevitably, at the beginning of a text line.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 @defun window-start &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 @cindex window top line
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 This function returns the display-start position of window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 @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
1154 used. For example,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 (window-start)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @result{} 7058
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1163 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
1164 display-start position is set to a display-start position recently used
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 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
1166
12596
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1167 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
1168 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
1169 point appears on the screen. Nothing except redisplay automatically
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1170 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
1171 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
1172 redisplay.
12596
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1173
ffe0de415152 Explain how redisplay updates window-start.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1174 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
1175 description of @code{count-lines} in @ref{Text Lines}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1178 @defun window-end &optional window update
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 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
1180 @var{window}. If @var{window} is @code{nil}, the selected window is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 used.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1182
11510
e5d3814e783a Update info on window-end.
Richard M. Stallman <rms@gnu.org>
parents: 8926
diff changeset
1183 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
1184 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
1185 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
1186
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1187 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
1188 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
1189 In that case, this function returns @code{nil}.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1190
38380
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1191 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
1192 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
1193 @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
1194 @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
1195 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
1196
99b267c1ccbd Explain window-end never scrolls the window.
Richard M. Stallman <rms@gnu.org>
parents: 36352
diff changeset
1197 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
1198 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
1199 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
1200 @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
1201 text will end if scrolling is not required.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 @end defun
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 @defun set-window-start window position &optional noforce
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 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
1206 @var{position} in @var{window}'s buffer. It returns @var{position}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 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
1209 buffer is displayed. Normally, they change the display-start position
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 (that is, scroll the window) whenever necessary to make point visible.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 However, if you specify the start position with this function using
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @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
1213 @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
1214 screen. If this does place point off screen, the display routines move
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 point to the left margin on the middle line in the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 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
1218 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
1219 routines will automatically move point if it is still 1 when redisplay
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 occurs. Here is an example:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 ;; @r{Here is what @samp{foo} looks like before executing}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 ;; @r{the @code{set-window-start} expression.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @point{}This is the contents of buffer foo.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 2
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 3
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 6
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 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 (set-window-start
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 (selected-window)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 (1+ (window-start)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @result{} 2
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
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 ;; @r{Here is what @samp{foo} looks like after executing}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 ;; @r{the @code{set-window-start} expression.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 his is the contents of buffer foo.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 2
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 3
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @point{}4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 6
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 ---------- Buffer: foo ----------
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260 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
1261 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
1262 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
1263 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264
34390
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1265 @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
1266 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
1267 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
1268 @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
1269 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
1270 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
1271 @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
1272 @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
1273
7d0d54bf89f4 (Window Start): Update documentation for `pos-visible-in-window-p'.
Miles Bader <miles@gnu.org>
parents: 34307
diff changeset
1274 Here is an example:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 (or (pos-visible-in-window-p
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 (point) (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 (recenter 0))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1285 @node Textual Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1286 @section Textual Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1287 @cindex textual scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1288 @cindex scrolling textually
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1290 @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
1291 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
1292 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
1293 point on the screen.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1294
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1295 Textual scrolling was formerly called ``vertical scrolling,'' but we
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1296 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
1297 scrolling feature (@pxref{Vertical Scrolling}).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299 In the commands @code{scroll-up} and @code{scroll-down}, the directions
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 ``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
1301 you are looking through the window. Imagine that the text is
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302 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
1303 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
1304 buffer and repeatedly call @code{scroll-down}, you will eventually see
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305 the beginning of the buffer.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 Some people have urged that the opposite convention be used: they
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 imagine that the window moves over text that remains in place. Then
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 ``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
1310 more consistent with the actual relationship between windows and the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 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
1312 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
1313 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
1314 names that fit the user's point of view.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1316 The textual scrolling functions (aside from
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1317 @code{scroll-other-window}) have unpredictable results if the current
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1318 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
1319 window. @xref{Current Buffer}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 @deffn Command scroll-up &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 This function scrolls the text in the selected window upward
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @var{count} lines. If @var{count} is negative, scrolling is actually
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 downward.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 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
1327 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
1328 the window (not counting its mode line).
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 @code{scroll-up} returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 @deffn Command scroll-down &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 This function scrolls the text in the selected window downward
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 @var{count} lines. If @var{count} is negative, scrolling is actually
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336 upward.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 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
1339 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
1340 the window (not counting its mode line).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 @code{scroll-down} returns @code{nil}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 @deffn Command scroll-other-window &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 This function scrolls the text in another window upward @var{count}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 lines. Negative values of @var{count}, or @code{nil}, are handled
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 as in @code{scroll-up}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1350 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
1351 @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
1352 already displayed, @code{scroll-other-window} displays it in some
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1353 window.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1354
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1355 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
1356 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
1357 scroll, when the minibuffer is selected, by setting the variable
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 @code{minibuffer-scroll-window}. This variable has no effect when any
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 other window is selected. @xref{Minibuffer Misc}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 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
1362 window is the one at the bottom right corner. In this case,
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @code{scroll-other-window} attempts to scroll the minibuffer. If the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 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
1365 line reappears after the echo area momentarily displays the message
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 ``Beginning of buffer''.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 @c Emacs 19 feature
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @defvar other-window-scroll-buffer
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 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
1372 which buffer to scroll.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 @end defvar
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1375 @defopt scroll-margin
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1376 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
1377 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
1378 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
1379 redisplay scrolls the text automatically (if possible) to move point
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1380 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
1381 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1382
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1383 @defopt scroll-conservatively
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 This variable controls how scrolling is done automatically when point
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1385 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
1386 positive integer @var{n}, then redisplay scrolls the text up to
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1387 @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
1388 proper view. This action is called @dfn{conservative scrolling}.
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1389 Otherwise, scrolling happens in the usual way, under the control of
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1390 other variables such as @code{scroll-up-aggressively} and
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1391 @code{scroll-down-aggressively}.
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1392
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1393 The default value is zero, which means that conservative scrolling
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1394 never happens.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1395 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1396
42983
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1397 @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
1398 @tindex scroll-down-aggressively
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1399 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
1400 @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
1401 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
1402 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
1403 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
1404 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
1405 scrolling.
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1406
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26394
diff changeset
1407 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
1408 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
1409 fashion.
26210
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1410 @end defopt
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1411
42983
f939e64a198b Exchange meanings of scroll-up-aggressively and scroll-down-aggressively.
Richard M. Stallman <rms@gnu.org>
parents: 42895
diff changeset
1412 @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
1413 @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
1414 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
1415 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
1416 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1417 @end defopt
fc4fefae9970 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1418
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1419 @defopt scroll-step
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1420 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
1421 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
1422 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
1423 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
1424 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1425
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1426 @defopt scroll-preserve-screen-position
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1427 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
1428 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
1429 possible.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 @defopt next-screen-context-lines
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433 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
1434 retain when scrolling by full screens. For example, @code{scroll-up}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 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
1436 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
1437 @code{2}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1438 @end defopt
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 @deffn Command recenter &optional count
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 @cindex centering point
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1442 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
1443 displayed at a specified vertical position within the window. It does
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1444 not ``move point'' with respect to the text.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445
42985
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1446 If @var{count} is a nonnegative number, that puts the line containing
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1447 point @var{count} lines down from the top of the window. If
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1448 @var{count} is a negative number, then it counts upward from the
0750cae9d8c8 Clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 42983
diff changeset
1449 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
1450 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
1451 stands for the line in the middle of the window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 If @var{count} is @code{nil}, @code{recenter} puts the line containing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 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
1455 selected frame.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 When @code{recenter} is called interactively, @var{count} is the raw
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @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
1460 @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
1461 top.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1463 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
1464 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
1465 separate key binding to do this. For example,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 (defun line-to-top-of-window ()
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 "Scroll current line to top of window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 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
1472 (interactive)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 (recenter 0))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1475 (global-set-key [kp-multiply] 'line-to-top-of-window)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1480 @node Vertical Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1481 @section Vertical Fractional Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1482 @cindex Vertical Fractional Scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1483
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1484 @dfn{Vertical fractional scrolling} means shifting the image in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1485 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
1486 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
1487 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
1488 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
1489 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
1490 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
1491
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1492 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
1493 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
1494 .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
1495 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
1496 somewhat over three times the normal line height.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1497
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1498 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
1499 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
1500 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
1501 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
1502
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1503 @defun window-vscroll &optional window
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1504 This function returns the current vertical scroll position of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1505 @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
1506 used.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1507
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1508 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1509 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1510 (window-vscroll)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1511 @result{} 0
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1512 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1513 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1514 @end defun
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 @defun set-window-vscroll window lines
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1517 This function sets @var{window}'s vertical scroll position to
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1518 @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
1519 not, it is taken as zero.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1520
41504
236397d27903 (Vertical Scrolling): Document what does nil mean as the first arg of
Eli Zaretskii <eliz@gnu.org>
parents: 40333
diff changeset
1521 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
1522
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1523 The actual vertical scroll position must always correspond
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1524 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
1525 is rounded accordingly.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1526
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1527 The return value is the result of this rounding.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1528
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1529 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1530 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1531 (set-window-vscroll (selected-window) 1.2)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1532 @result{} 1.13
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1533 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1534 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1535 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1536
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @node Horizontal Scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 @section Horizontal Scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @cindex horizontal scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1541 @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
1542 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
1543 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
1544 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
1545 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
1546 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
1547 characters appear at the right. The usual value is zero.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1548
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1549 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
1550 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
1551 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
1552 times the normal character width. How many characters actually
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1553 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
1554 line to line.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1555
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1556 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
1557 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
1558 not like that of textual or vertical scrolling. Textual scrolling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1559 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
1560 scrolling moves the window contents contiguously; but horizontal
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1561 scrolling causes part of @emph{each line} to go off screen.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 Usually, no horizontal scrolling is in effect; then the leftmost
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 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
1565 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
1566 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
1567 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
1568 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
1569 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
1570 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
1571 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
1572 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
1573 left edge.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574
43665
717f4f88556c (Horizontal Scrolling): Rename automatic-hscrolling to auto-hscroll-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 43257
diff changeset
1575 @vindex auto-hscroll-mode
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1576 In Emacs 21, redisplay automatically alters the horizontal scrolling
34749
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1577 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
1578 @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
1579 horizontal scrolling value explicitly. The value you specify serves as
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1580 a lower bound for automatic scrolling, i.e. automatic scrolling
3a0a4c2b6633 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 34390
diff changeset
1581 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
1582
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1583 @deffn Command scroll-left &optional count
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 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
1585 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
1586 for @var{count} is the window width, minus 2.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1587
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1588 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
1589 effect after the change---just like the value returned by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1590 @code{window-hscroll} (below).
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1593 @deffn Command scroll-right &optional count
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594 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
1595 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
1596 for @var{count} is the window width, minus 2.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1597
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1598 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
1599 effect after the change---just like the value returned by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1600 @code{window-hscroll} (below).
6564
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 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
1603 position where the total leftward scrolling is zero, attempts to scroll
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 any farther right have no effect.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 @defun window-hscroll &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 This function returns the total leftward horizontal scrolling of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609 @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
1610 is scrolled left past the left margin.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612 The value is never negative. It is zero when no horizontal scrolling
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613 has been done in @var{window} (which is usually the case).
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 If @var{window} is @code{nil}, the selected window is used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619 (window-hscroll)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 @result{} 0
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 (scroll-left 5)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624 @result{} 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 (window-hscroll)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 @result{} 5
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633 @defun set-window-hscroll window columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 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
1635 @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
1636 @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
1637 Fractional values of @var{columns} are not supported at present.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638
45679
85f61bf6ce1d Explain why set-window-hscroll may appear to fail to work.
Richard M. Stallman <rms@gnu.org>
parents: 45583
diff changeset
1639 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
1640 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
1641 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
1642 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
1643 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
1644 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
1645 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
1646
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1647 The value returned is @var{columns}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1648
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651 (set-window-hscroll (selected-window) 10)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1652 @result{} 10
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1654 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657 Here is how you can determine whether a given position @var{position}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 is off the screen due to horizontal scrolling:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 @group
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1662 (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
1663 (save-excursion
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1664 (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
1665 (and
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1666 (>= (- (current-column) (window-hscroll window)) 0)
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1667 (< (- (current-column) (window-hscroll window))
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1668 (window-width window)))))
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1669 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670 @end example
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 @node Size of Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1673 @section The Size of a Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1674 @cindex window size
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1675 @cindex size of window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1676
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677 An Emacs window is rectangular, and its size information consists of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1678 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
1679 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
1680 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
1681 characters that separates side-by-side windows.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 The following three functions return size information about a window:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1684
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685 @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
1686 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
1687 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
1688 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
1689 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
1690 frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 If @var{window} is @code{nil}, the function uses the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1695 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696 (window-height)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697 @result{} 23
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1699 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 (split-window-vertically)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1701 @result{} #<window 4 on windows.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1702 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1703 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704 (window-height)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705 @result{} 11
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1708 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1709
42819
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1710 @tindex window-body-height
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1711 @defun window-body-height &optional window
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48700
diff changeset
1712 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
1713 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
1714 @end defun
401375284bf0 Clarify how window-height relates to other things.
Richard M. Stallman <rms@gnu.org>
parents: 41504
diff changeset
1715
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1716 @defun window-width &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 This function returns the number of columns in @var{window}. If
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 @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
1719 @code{frame-width} on that frame. The width does not include the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 window's scroll bar or the column of @samp{|} characters that separates
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 side-by-side windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723 If @var{window} is @code{nil}, the function uses the selected window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 (window-width)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 @result{} 80
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1732
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1733 @defun window-edges &optional window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1734 This function returns a list of the edge coordinates of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1735 If @var{window} is @code{nil}, the selected window is used.
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 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
1738 @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
1739 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
1740 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
1741 the bottommost row used by @var{window} and its mode-line.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1743 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
1744 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
1745 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
1746 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
1747 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
1748 between the right and left edges.
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1749 @end defun
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1751 @defun window-inside-edges window
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1752 This is similar to @code{window-edges}, but the edge values
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1753 it returns include only the text area of the window. They
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1754 do not include the header line, mode line, scroll bar or
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1755 vertical separator, fringes, or display margins.
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1756 @end defun
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1757
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1758 Here are the results obtained on a typical 24-line terminal with just
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1759 one window, with menu bar enabled:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 (window-edges (selected-window))
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1764 @result{} (0 1 80 23)
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1765 @end group
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1766 @group
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1767 (window-inside-edges (selected-window))
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1768 @result{} (0 1 80 22)
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1772 @noindent
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1773 The bottom edge is at line 23 because the last line is the echo area.
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1774 The bottom inside edge is at line 22, which is the window's mode line.
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1775
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1776 If @var{window} is at the upper left corner of its frame, and there is
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1777 no menu bar, then @var{bottom} returned by @code{window-edges} is the
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1778 same as the value of @code{(window-height)}, @var{right} is almost the
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1779 same as the value of @code{(window-width)}, and @var{top} and
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1780 @var{left} are zero. For example, the edges of the following window
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1781 are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1782 columns, the last column of the window (column 7) holds a border
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1783 rather than text. The last row (row 4) holds the mode line, shown
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1784 here with @samp{xxxxxxxxx}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1785
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1786 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1787 @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
1788 0
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 _______
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1790 0 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1791 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1792 | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1793 | |
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 xxxxxxxxx 4
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1795
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1796 7
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 @end example
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 In the following example, let's suppose that the frame is 7
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1801 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1802 and the edges of the right window are @w{@samp{4 0 7 3}}.
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1803 The inside edges of the left window are @w{@samp{0 0 3 2}},
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1804 and the inside edges of the right window are @w{@samp{4 0 7 2}},
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1806 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808 ___ ___
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1809 | | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1810 | | |
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1811 xxxxxxxxx
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1812
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1813 0 34 7
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1814 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815 @end example
51924
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1816
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1817 @defun window-pixel-edges window
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1818 This function is like @code{window-edges} except that, on a graphical
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1819 display, the edge values are measured in pixels instead of in
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1820 character lines and columns.
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1821 @end defun
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1822
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1823 @defun window-inside-pixel-edges window
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1824 This function is like @code{window-inside-edges} except that, on a
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1825 graphical display, the edge values are measured in pixels instead of
a05f23194471 (Selecting Windows): New arg to select-window.
Richard M. Stallman <rms@gnu.org>
parents: 51704
diff changeset
1826 in character lines and columns.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829 @node Resizing Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 @section Changing the Size of a Window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 @cindex window resizing
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 @cindex changing window size
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833 @cindex window size, changing
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 The window size functions fall into two classes: high-level commands
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 that change the size of windows and low-level functions that access
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 window size. Emacs does not permit overlapping windows or gaps between
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 windows, so resizing one window affects other windows.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 @deffn Command enlarge-window size &optional horizontal
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1841 This function makes the selected window @var{size} lines taller,
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 stealing lines from neighboring windows. It takes the lines from one
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 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
1844 If a window from which lines are stolen shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 @code{window-min-height} lines, that window disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847 If @var{horizontal} is non-@code{nil}, this function makes
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848 @var{window} wider by @var{size} columns, stealing columns instead of
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 lines. If a window from which columns are stolen shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850 @code{window-min-width} columns, that window disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1852 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
1853 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
1854 frame.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1856 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
1857 stolen, and some of them specify fixed size (using
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1858 @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
1859 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
1860 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
1861 instead.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1862
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863 If @var{size} is negative, this function shrinks the window by
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864 @minus{}@var{size} lines or columns. If that makes the window smaller
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865 than the minimum size (@code{window-min-height} and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1866 @code{window-min-width}), @code{enlarge-window} deletes the window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1867
15668
194145c1a2c0 Added Richard's diffs to this file, fixed a couple of small bugs
Daniel Hagerty <hag@gnu.org>
parents: 13275
diff changeset
1868 @code{enlarge-window} returns @code{nil}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1869 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1870
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1871 @deffn Command enlarge-window-horizontally columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1872 This function makes the selected window @var{columns} wider.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1873 It could be defined as follows:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1874
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1875 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1876 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1877 (defun enlarge-window-horizontally (columns)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1878 (enlarge-window columns t))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1879 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1880 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1881 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1882
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1883 @deffn Command shrink-window size &optional horizontal
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1884 This function is like @code{enlarge-window} but negates the argument
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885 @var{size}, making the selected window smaller by giving lines (or
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886 columns) to the other windows. If the window shrinks below
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 @code{window-min-height} or @code{window-min-width}, then it disappears.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1888
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1889 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
1890 lines or columns.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1892
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1893 @deffn Command shrink-window-horizontally columns
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1894 This function makes the selected window @var{columns} narrower.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1895 It could be defined as follows:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1896
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1897 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1898 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1899 (defun shrink-window-horizontally (columns)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1900 (shrink-window columns t))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1901 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1902 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1903 @end deffn
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1904
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1905 @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
1906 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
1907 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
1908 @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
1909 it defaults to the selected window.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1910
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1911 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
1912 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
1913 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
1914 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
1915 @end deffn
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1916
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1917 @tindex window-size-fixed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1918 @defvar window-size-fixed
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1919 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
1920 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
1921 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
1922 (This feature is new in Emacs 21.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1923
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1924 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
1925 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
1926 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
1927
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1928 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
1929 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
1930 one) displaying that buffer have fixed size.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1931
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1932 Explicit size-change functions such as @code{enlarge-window}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1933 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
1934 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
1935 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
1936
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1937 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1938 (let ((window-size-fixed nil))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1939 (enlarge-window 10))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1940 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1941
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1942 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
1943 fixed-size window, if there is no other alternative.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1944 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
1945
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946 @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
1947 The following two variables constrain the window-structure-changing
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948 functions to a minimum height and width.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1950 @defopt window-min-height
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951 The value of this variable determines how short a window may become
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 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
1953 @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
1954 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
1955
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1956 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
1957 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
1958 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 @defopt window-min-width
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961 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
1962 before it is automatically deleted. Making a window smaller than
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 @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
1964 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
1965
589485c2358e For window-min-height, the absolute minimum is 1.
Richard M. Stallman <rms@gnu.org>
parents: 42819
diff changeset
1966 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
1967 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
1968 @end defopt
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 @node Coordinates and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971 @section Coordinates and Windows
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972
8491
320375e58ee3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1973 This section describes how to relate screen coordinates to windows.
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 @defun window-at x y &optional frame
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976 This function returns the window containing the specified cursor
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 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
1978 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
1979 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
1980
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 If you omit @var{frame}, the selected frame is used.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 @defun coordinates-in-window-p coordinates window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 This function checks whether a particular frame position falls within
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 the window @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1988 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
1989 . @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
1990 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
1991
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1992 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
1993 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
1994 what part of the window the position is in, as follows:
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996 @table @code
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1997 @item (@var{relx} . @var{rely})
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998 The coordinates are inside @var{window}. The numbers @var{relx} and
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1999 @var{rely} are the equivalent window-relative coordinates for the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000 specified position, counting from 0 at the top left corner of the
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 window.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003 @item mode-line
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004 The coordinates are in the mode line of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2006 @item header-line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2007 The coordinates are in the header line of @var{window}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2008
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2009 @item vertical-line
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2010 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
2011 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
2012 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
2013 window for these purposes.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2014
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2015 @item nil
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016 The coordinates are not in any part of @var{window}.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017 @end table
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 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
2020 argument because it always uses the frame that @var{window} is on.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2021 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2023 @node Window Configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2024 @section Window Configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025 @cindex window configurations
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 @cindex saving window information
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2028 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
2029 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
2030 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
2031 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
2032 @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
2033 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
2034 buffer; its value is not saved in the window configuration.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2035
45583
d7967cbc28b1 Improve explanation of special handling of point in current buffer.
Richard M. Stallman <rms@gnu.org>
parents: 43908
diff changeset
2036 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
2037 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
2038 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
2039 configuration. @xref{Frame Configurations}.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2040
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2041 @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
2042 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
2043 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
2044 is used.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2045 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2047 @defun set-window-configuration configuration
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2048 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
2049 specified by @var{configuration}, for the frame that @var{configuration}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2050 was created for.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2051
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2052 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
2053 returned by @code{current-window-configuration}. This configuration is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2054 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
2055 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
2056 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
2057 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2058 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
2059 old one.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2061 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
2062 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
2063 @code{window-min-width} and @code{minibuffer-scroll-window}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2064
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2065 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
2066 as @code{save-window-excursion}:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2067
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070 (let ((config (current-window-configuration)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071 (unwind-protect
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2072 (progn (split-window-vertically nil)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 @dots{})
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 (set-window-configuration config)))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 @defspec save-window-excursion forms@dots{}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080 This special form records the window configuration, executes @var{forms}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2081 in sequence, then restores the earlier window configuration. The window
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2082 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
2083 that is visible. It also includes the choice of selected window.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2084 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
2085 use @code{save-excursion} also, if you wish to preserve that.
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2086
51997
7f2fcfb45bf7 (Selecting Windows): save-selected-window saves selected window of each frame.
Richard M. Stallman <rms@gnu.org>
parents: 51924
diff changeset
2087 Don't use this construct when @code{save-selected-window} is sufficient.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2088
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2089 Exit from @code{save-window-excursion} always triggers execution of the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2090 @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
2091 whether the restored configuration actually differs from the one in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2092 effect at the end of the @var{forms}.)
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2093
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 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
2095 For example:
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2096
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2097 @example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2098 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2099 (split-window)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 @result{} #<window 25 on control.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2103 (setq w (selected-window))
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2104 @result{} #<window 19 on control.texi>
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106 @group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 (save-window-excursion
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2108 (delete-other-windows w)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2109 (switch-to-buffer "foo")
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2110 'do-something)
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2111 @result{} do-something
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2112 ;; @r{The screen is now split again.}
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2113 @end group
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2114 @end example
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2115 @end defspec
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2116
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2117 @defun window-configuration-p object
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2118 This function returns @code{t} if @var{object} is a window configuration.
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2119 @end defun
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2120
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2121 @defun compare-window-configurations config1 config2
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2122 This function compares two window configurations as regards the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2123 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
2124 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
2125 aspects differ.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2126
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2127 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
2128 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
2129 saved point or mark.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2130 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2131
6564
d9652e184eec Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132 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
2133 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
2134 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
2135 operations on windows configurations.
21007
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 @node Window Hooks
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2138 @section Hooks for Window Scrolling and Changes
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2139
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2140 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
2141 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
2142 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
2143 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
2144 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
2145 @code{window-size-change-functions}. The paradigmatic use of these
50475
b65aa1d740eb Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents: 49961
diff changeset
2146 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
2147
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2148 @defvar window-scroll-functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2149 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
2150 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
2151 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
2152 display-start position.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2153
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2154 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
2155
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2156 These functions must be careful in using @code{window-end}
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2157 (@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
2158 the @var{update} argument to ensure you get it.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2159 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2160
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2161 @defvar window-size-change-functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2162 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
2163 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
2164 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
2165 occurred.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2166
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2167 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
2168 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
2169 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
2170 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
2171 present sizes and the previous sizes.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2172
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2173 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
2174 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
2175 counts, because it changes the sizes of the existing windows.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2176
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2177 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
2178 Configurations}) in these functions, because that always counts as a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2179 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
2180 over. In most cases, @code{save-selected-window} (@pxref{Selecting
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2181 Windows}) is what you need here.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2182 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2183
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2184 @defvar redisplay-end-trigger-functions
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2185 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
2186 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
2187 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
2188 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
2189 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
2190 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
2191 after the hook is run.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2192 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2193
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2194 @defun set-window-redisplay-end-trigger window position
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2195 This function sets @var{window}'s end trigger position at
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2196 @var{position}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2197 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2198
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
2199 @defun window-redisplay-end-trigger &optional window
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2200 This function returns @var{window}'s current end trigger position.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2201 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2202
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2203 @defvar window-configuration-change-hook
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2204 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
2205 of an existing frame. This includes splitting or deleting windows,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2206 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
2207 window. The frame whose window configuration has changed is the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2208 selected frame when this hook runs.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2209 @end defvar
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52151
diff changeset
2210
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52151
diff changeset
2211 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52151
diff changeset
2212 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52151
diff changeset
2213 @end ignore