Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
73b0cd50 | 3 | @c Copyright (C) 1990-1995, 1998-1999, 2001-2011 |
0c5413c8 | 4 | @c Free Software Foundation, Inc. |
b8d4c8d0 | 5 | @c See the file elisp.texi for copying conditions. |
6336d8c3 | 6 | @setfilename ../../info/windows |
b8d4c8d0 GM |
7 | @node Windows, Frames, Buffers, Top |
8 | @chapter Windows | |
9 | ||
b33b68a3 MR |
10 | This chapter describes the functions and variables related to Emacs |
11 | windows. @xref{Frames}, for how windows are assigned an area of screen | |
12 | available for Emacs to use. @xref{Display}, for information on how text | |
13 | is displayed in windows. | |
b8d4c8d0 GM |
14 | |
15 | @menu | |
16 | * Basic Windows:: Basic information on using windows. | |
b33b68a3 MR |
17 | * Windows and Frames:: Relating windows to the frame they appear on. |
18 | * Window Sizes:: Accessing a window's size. | |
19 | * Resizing Windows:: Changing the sizes of windows. | |
b8d4c8d0 GM |
20 | * Splitting Windows:: Splitting one window into two windows. |
21 | * Deleting Windows:: Deleting a window gives its space to other windows. | |
22 | * Selecting Windows:: The selected window is the one that you edit in. | |
23 | * Cyclic Window Ordering:: Moving around the existing windows. | |
24 | * Buffers and Windows:: Each window displays the contents of a buffer. | |
0e406a72 | 25 | * Switching Buffers:: Higher-level functions for switching to a buffer. |
d24880de | 26 | * Choosing Window:: How to choose a window for displaying a buffer. |
9ec20d36 CY |
27 | * Display Action Functions:: Subroutines for @code{display-buffer}. |
28 | * Choosing Window Options:: Extra options affecting how buffers are displayed. | |
0e406a72 | 29 | * Window History:: Each window remembers the buffers displayed in it. |
d24880de | 30 | * Dedicated Windows:: How to avoid displaying another buffer in |
a1401ab1 | 31 | a specific window. |
c419f5cb MR |
32 | * Quitting Windows:: How to restore the state prior to displaying a |
33 | buffer. | |
b8d4c8d0 | 34 | * Window Point:: Each window has its own location of point. |
0273ca3a MR |
35 | * Window Start and End:: Buffer positions indicating which text is |
36 | on-screen in a window. | |
b8d4c8d0 GM |
37 | * Textual Scrolling:: Moving text up and down through the window. |
38 | * Vertical Scrolling:: Moving the contents up and down on the window. | |
39 | * Horizontal Scrolling:: Moving the contents sideways on the window. | |
b8d4c8d0 | 40 | * Coordinates and Windows:: Converting coordinates to windows. |
b8d4c8d0 | 41 | * Window Configurations:: Saving and restoring the state of the screen. |
0273ca3a | 42 | * Window Parameters:: Associating additional information with windows. |
b8d4c8d0 GM |
43 | * Window Hooks:: Hooks for scrolling, window size changes, |
44 | redisplay going past a certain point, | |
45 | or window configuration changes. | |
46 | @end menu | |
47 | ||
b33b68a3 | 48 | |
b8d4c8d0 GM |
49 | @node Basic Windows |
50 | @section Basic Concepts of Emacs Windows | |
51 | @cindex window | |
b8d4c8d0 | 52 | |
291d142b CY |
53 | A @dfn{window} is a area of the screen which is used to display a |
54 | buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a | |
55 | special Lisp object type. | |
b8d4c8d0 GM |
56 | |
57 | @cindex multiple windows | |
291d142b CY |
58 | Windows are grouped into frames (@pxref{Frames}). Each frame |
59 | contains at least one window; the user can subdivide it into multiple, | |
60 | non-overlapping windows to view several buffers at once. Lisp | |
61 | programs can use multiple windows for a variety of purposes. In | |
62 | Rmail, for example, you can view a summary of message titles in one | |
63 | window, and the contents of the selected message in another window. | |
b8d4c8d0 | 64 | |
b33b68a3 MR |
65 | @cindex terminal screen |
66 | @cindex screen of terminal | |
291d142b CY |
67 | Emacs uses the word ``window'' with a different meaning than in |
68 | graphical desktop environments and window systems, such as the X | |
69 | Window System. When Emacs is run on X, each of its graphical X | |
70 | windows is an Emacs frame (containing one or more Emacs windows). | |
71 | When Emacs is run on a text-only terminal, the frame fills the entire | |
72 | terminal screen. | |
b8d4c8d0 | 73 | |
b8d4c8d0 | 74 | @cindex tiled windows |
291d142b CY |
75 | Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap |
76 | within the area of the frame. When a window is created, resized, or | |
77 | deleted, the change in window space is taken from or given to the | |
78 | adjacent windows, so that the total area of the frame is unchanged. | |
b33b68a3 MR |
79 | |
80 | @cindex live windows | |
81 | @cindex internal windows | |
291d142b CY |
82 | A @dfn{live window} is one that is actually displaying a buffer in a |
83 | frame. Such a window can be @dfn{deleted}, i.e. removed from the | |
84 | frame (@pxref{Deleting Windows}); then it is no longer live, but the | |
85 | Lisp object representing it might be still referenced from other Lisp | |
86 | objects. A deleted window may be brought back to life by restoring a | |
87 | saved window configuration (@pxref{Window Configurations}). | |
88 | ||
89 | @defun windowp object | |
90 | This function returns @code{t} if @var{object} is a window (whether or | |
91 | not it is live). Otherwise, it returns @code{nil}. | |
92 | @end defun | |
b33b68a3 MR |
93 | |
94 | @defun window-live-p object | |
95 | This function returns @code{t} if @var{object} is a live window and | |
291d142b | 96 | @code{nil} otherwise. A live window is one that displays a buffer. |
b33b68a3 MR |
97 | @end defun |
98 | ||
291d142b CY |
99 | The windows in each frame are organized into a @dfn{window tree}. |
100 | @xref{Windows and Frames}. The leaf nodes of each window tree are | |
101 | live windows---the ones actually displaying buffers. The internal | |
102 | nodes of the window tree are internal windows, which are not live. | |
103 | You can distinguish internal windows from deleted windows with | |
104 | @code{window-valid-p}. | |
105 | ||
106 | @defun window-valid-p object | |
107 | This function returns @code{t} if @var{object} is a live window, or an | |
108 | internal window in a window tree. Otherwise, it returns @code{nil}, | |
109 | including for the case where @var{object} is a deleted window. | |
b33b68a3 MR |
110 | @end defun |
111 | ||
112 | @cindex selected window | |
291d142b CY |
113 | In each frame, at any time, exactly one Emacs window is designated |
114 | as @dfn{selected within the frame}. For the selected frame, that | |
115 | window is called the @dfn{selected window}---the one in which most | |
116 | editing takes place, and in which the cursor for selected windows | |
117 | appears (@pxref{Cursor Parameters}). The selected window's buffer is | |
118 | usually also the current buffer, except when @code{set-buffer} has | |
119 | been used (@pxref{Current Buffer}). As for non-selected frames, the | |
120 | window selected within the frame becomes the selected window if the | |
121 | frame is ever selected. @xref{Selecting Windows}. | |
b33b68a3 MR |
122 | |
123 | @defun selected-window | |
291d142b CY |
124 | This function returns the selected window (which is always a live |
125 | window). | |
b33b68a3 MR |
126 | @end defun |
127 | ||
b33b68a3 MR |
128 | @node Windows and Frames |
129 | @section Windows and Frames | |
130 | ||
291d142b | 131 | Each window belongs to exactly one frame (@pxref{Frames}). |
b33b68a3 MR |
132 | |
133 | @defun window-frame window | |
291d142b CY |
134 | This function returns the frame that the window @var{window} belongs |
135 | to. If @var{window} is @code{nil}, it defaults to the selected | |
136 | window. | |
b33b68a3 MR |
137 | @end defun |
138 | ||
291d142b CY |
139 | @defun window-list &optional frame minibuffer window |
140 | This function returns a list of live windows belonging to the frame | |
141 | @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to | |
142 | the selected frame. | |
b33b68a3 | 143 | |
291d142b CY |
144 | The optional argument @var{minibuffer} specifies whether to include |
145 | the minibuffer window in the returned list. If @var{minibuffer} is | |
146 | @code{t}, the minibuffer window is included. If @var{minibuffer} is | |
147 | @code{nil} or omitted, the minibuffer window is included only if it is | |
148 | active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the | |
149 | minibuffer window is never included. | |
b33b68a3 | 150 | |
291d142b CY |
151 | The optional argument @var{window}, if non-@code{nil}, should be a |
152 | live window on the specified frame; then @var{window} will be the | |
153 | first element in the returned list. If @var{window} is omitted or | |
154 | @code{nil}, the window selected within the frame is first element. | |
b33b68a3 MR |
155 | @end defun |
156 | ||
157 | @cindex window tree | |
291d142b CY |
158 | @cindex root window |
159 | Windows in the same frame are organized into a @dfn{window tree}, | |
160 | whose leaf nodes are the live windows. The internal nodes of a window | |
161 | tree are not live; they exist for the purpose of organizing the | |
162 | relationships between live windows. The root node of a window tree is | |
163 | called the @dfn{root window}. It can be either a live window (if the | |
164 | frame has just one window), or an internal window. | |
165 | ||
166 | A minibuffer window (@pxref{Minibuffer Windows}) is not part of its | |
167 | frame's window tree unless the frame is a minibuffer-only frame. | |
168 | Nonetheless, most of the functions in this section accept the | |
169 | minibuffer window as an argument. Also, the function | |
170 | @code{window-tree} described at the end of this section lists the | |
171 | minibuffer window alongside the actual window tree. | |
b33b68a3 MR |
172 | |
173 | @defun frame-root-window &optional frame-or-window | |
291d142b CY |
174 | This function returns the root window for @var{frame-or-window}. The |
175 | argument @var{frame-or-window} should be either a window or a frame; | |
176 | if omitted or @code{nil}, it defaults to the selected frame. If | |
177 | @var{frame-or-window} is a window, the return value is the root window | |
178 | of that window's frame. | |
b33b68a3 MR |
179 | @end defun |
180 | ||
291d142b CY |
181 | @cindex parent window |
182 | @cindex child window | |
183 | @cindex sibling window | |
184 | When a window is split, there are two live windows where previously | |
185 | there was one. One of these is represented by the same Lisp window | |
186 | object as the original window, and the other is represented by a | |
187 | newly-created Lisp window object. Both of these live windows become | |
188 | leaf nodes of the window tree, as @dfn{child windows} of a single | |
189 | internal window. If necessary, Emacs automatically creates this | |
190 | internal window, which is also called the @dfn{parent window}, and | |
191 | assigns it to the appropriate position in the window tree. A set of | |
192 | windows that share the same parent are called @dfn{siblings}. | |
b33b68a3 MR |
193 | |
194 | @cindex parent window | |
195 | @defun window-parent &optional window | |
291d142b CY |
196 | This function returns the parent window of @var{window}. If |
197 | @var{window} is omitted or @code{nil}, it defaults to the selected | |
198 | window. The return value is @code{nil} if @var{window} has no parent | |
199 | (i.e. it is a minibuffer window or the root window of its frame). | |
b33b68a3 MR |
200 | @end defun |
201 | ||
291d142b CY |
202 | Each internal window always has at least two child windows. If this |
203 | number falls to one as a result of window deletion, Emacs | |
204 | automatically deletes the internal window, and its sole remaining | |
205 | child window takes its place in the window tree. | |
206 | ||
207 | Each child window can be either a live window, or an internal window | |
208 | (which in turn would have its own child windows). Therefore, each | |
209 | internal window can be thought of as occupying a certain rectangular | |
210 | @dfn{screen area}---the union of the areas occupied by the live | |
211 | windows that are ultimately descended from it. | |
b33b68a3 MR |
212 | |
213 | @cindex window combination | |
214 | @cindex vertical combination | |
215 | @cindex horizontal combination | |
291d142b CY |
216 | For each internal window, the screen areas of the immediate children |
217 | are arranged either vertically or horizontally (never both). If the | |
218 | child windows are arranged one above the other, they are said to form | |
219 | a @dfn{vertical combination}; if they are arranged side by side, they | |
220 | are said to form a @dfn{horizontal combination}. Consider the | |
221 | following example: | |
b33b68a3 MR |
222 | |
223 | @smallexample | |
224 | @group | |
225 | ______________________________________ | |
226 | | ______ ____________________________ | | |
227 | || || __________________________ || | |
291d142b CY |
228 | || ||| ||| |
229 | || ||| ||| | |
230 | || ||| ||| | |
b33b68a3 MR |
231 | || |||____________W4____________||| |
232 | || || __________________________ || | |
233 | || ||| ||| | |
291d142b | 234 | || ||| ||| |
b33b68a3 MR |
235 | || |||____________W5____________||| |
236 | ||__W2__||_____________W3_____________ | | |
237 | |__________________W1__________________| | |
238 | ||
239 | @end group | |
240 | @end smallexample | |
241 | ||
291d142b CY |
242 | @noindent |
243 | The root window of this frame is an internal window, @code{W1}. Its | |
244 | child windows form a horizontal combination, consisting of the live | |
245 | window @code{W2} and the internal window @code{W3}. The child windows | |
246 | of @code{W3} form a vertical combination, consisting of the live | |
247 | windows @code{W4} and @code{W5}. Hence, the live windows in this | |
248 | window tree are @code{W2} @code{W4}, and @code{W5}. | |
249 | ||
250 | The following functions can be used to retrieve a child window of an | |
251 | internal window, and the siblings of a child window. | |
252 | ||
253 | @defun window-top-child window | |
254 | This function returns the topmost child window of @var{window}, if | |
255 | @var{window} is an internal window whose children form a vertical | |
256 | combination. For any other type of window, the return value is | |
257 | @code{nil}. | |
b33b68a3 MR |
258 | @end defun |
259 | ||
291d142b CY |
260 | @defun window-left-child window |
261 | This function returns the leftmost child window of @var{window}, if | |
262 | @var{window} is an internal window whose children form a horizontal | |
263 | combination. For any other type of window, the return value is | |
264 | @code{nil}. | |
b33b68a3 MR |
265 | @end defun |
266 | ||
267 | @defun window-child window | |
291d142b CY |
268 | This function returns the first child window of the internal window |
269 | @var{window}---the topmost child window for a vertical combination, or | |
270 | the leftmost child window for a horizontal combination. If | |
271 | @var{window} is a live window, the return value is @code{nil}. | |
b33b68a3 MR |
272 | @end defun |
273 | ||
3d8daefe | 274 | @defun window-combined-p &optional window horizontal |
291d142b CY |
275 | This function returns a non-@code{nil} value if and only if |
276 | @var{window} is part of a vertical combination. If @var{window} is | |
277 | omitted or nil, it defaults to the selected one. | |
b33b68a3 | 278 | |
291d142b CY |
279 | If the optional argument @var{horizontal} is non-@code{nil}, this |
280 | means to return non-@code{nil} if and only if @var{window} is part of | |
281 | a horizontal combination. | |
b33b68a3 MR |
282 | @end defun |
283 | ||
b33b68a3 | 284 | @defun window-next-sibling &optional window |
291d142b CY |
285 | This function returns the next sibling of the window @var{window}. If |
286 | omitted or @code{nil}, @var{window} defaults to the selected window. | |
287 | The return value is @code{nil} if @var{window} is the last child of | |
288 | its parent. | |
b33b68a3 MR |
289 | @end defun |
290 | ||
291 | @defun window-prev-sibling &optional window | |
291d142b CY |
292 | This function returns the previous sibling of the window @var{window}. |
293 | If omitted or @code{nil}, @var{window} defaults to the selected | |
294 | window. The return value is @code{nil} if @var{window} is the first | |
295 | child of its parent. | |
b33b68a3 MR |
296 | @end defun |
297 | ||
291d142b CY |
298 | The functions @code{window-next-sibling} and |
299 | @code{window-prev-sibling} should not be confused with the functions | |
300 | @code{next-window} and @code{previous-window} which respectively | |
301 | return the next and previous window in the cyclic ordering of windows | |
302 | (@pxref{Cyclic Window Ordering}). | |
b33b68a3 | 303 | |
291d142b CY |
304 | You can use the following functions to find the first live window on |
305 | a frame, and to retrieve the entire window tree of a frame: | |
b33b68a3 MR |
306 | |
307 | @defun frame-first-window &optional frame-or-window | |
308 | This function returns the live window at the upper left corner of the | |
309 | frame specified by @var{frame-or-window}. The argument | |
310 | @var{frame-or-window} must denote a window or a live frame and defaults | |
311 | to the selected frame. If @var{frame-or-window} specifies a window, | |
312 | this function returns the first window on that window's frame. Under | |
313 | the assumption that the frame from our canonical example is selected | |
314 | @code{(frame-first-window)} returns @code{W2}. | |
315 | @end defun | |
316 | ||
b33b68a3 | 317 | @defun window-tree &optional frame |
291d142b CY |
318 | This function returns a list representing the window tree for frame |
319 | @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to | |
320 | the selected frame. | |
b33b68a3 MR |
321 | |
322 | The return value is a list of the form @code{(@var{root} @var{mini})}, | |
291d142b CY |
323 | where @var{root} represents the window tree of the frame's root |
324 | window, and @var{mini} is the frame's minibuffer window. | |
b33b68a3 | 325 | |
291d142b CY |
326 | If the root window is live, @var{root} is that window itself. |
327 | Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} | |
328 | @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal | |
329 | combination and @code{t} for a vertical combination, @var{edges} gives | |
330 | the size and position of the combination, and the remaining elements | |
331 | are the child windows. Each child window may again be a window object | |
332 | (for a live window) or a list with the same format as above (for an | |
333 | internal window). The @var{edges} element is a list @code{(@var{left} | |
334 | @var{top} @var{right} @var{bottom})}, similar to the value returned by | |
335 | @code{window-edges} (@pxref{Coordinates and Windows}). | |
b33b68a3 MR |
336 | @end defun |
337 | ||
b33b68a3 MR |
338 | @node Window Sizes |
339 | @section Window Sizes | |
340 | @cindex window size | |
341 | @cindex size of window | |
342 | ||
343 | Emacs windows are rectangular. The structure of a live window can be | |
344 | roughly sketched as follows: | |
345 | ||
346 | @smallexample | |
347 | @group | |
348 | _________________________________________ | |
349 | ^ |______________ Header Line_______________| | |
350 | | |LS|LF|LM| |RM|RF|RS| ^ | |
351 | | | | | | | | | | | | |
352 | Window | | | | Text Area | | | | Window | |
353 | Total | | | | (Window Body) | | | | Body | |
354 | Height | | | | | | | | Height | |
355 | | | | | |<- Window Body Width ->| | | | | | |
356 | | |__|__|__|_______________________|__|__|__| v | |
357 | v |_______________ Mode Line _______________| | |
358 | ||
359 | <----------- Window Total Width --------> | |
360 | ||
361 | @end group | |
362 | @end smallexample | |
363 | ||
364 | @cindex window body | |
365 | @cindex body of a window | |
366 | The text area constitutes the body of the window. In its most simple | |
367 | form, a window consists of its body alone. LS and RS stand for the left | |
368 | and right scroll bar (@pxref{Scroll Bars}) respectively. Only one of | |
369 | them can be present at any time. LF and RF denote the left and right | |
370 | fringe, see @ref{Fringes}. LM and RM, finally, stand for the left and | |
371 | right display margin, see @ref{Display Margins}. The header line, if | |
372 | present, is located above theses areas, the mode line below, see | |
373 | @ref{Mode Line Format}. | |
374 | ||
375 | @cindex window height | |
376 | @cindex total window height | |
377 | @cindex height of a window | |
378 | @cindex total height of a window | |
379 | The @dfn{total height of a window} is specified as the total number of | |
380 | lines occupied by the window. Any mode or header line is included in a | |
381 | window's total height. For an internal window, the total height is | |
382 | calculated recursively from the total heights of its child windows. | |
383 | ||
384 | @cindex window width | |
385 | @cindex total window width | |
386 | @cindex width of a window | |
387 | @cindex total width of a window | |
388 | The @dfn{total width of a window} denotes the total number of columns of | |
389 | the window. Any scroll bar and the column of @samp{|} characters that | |
390 | separate the window from its right sibling are included in a window's | |
391 | total width. On a window-system, fringes and display margins are | |
392 | included in a window's total width too. For an internal window, the | |
393 | total width is calculated recursively from the total widths of its child | |
394 | windows. | |
395 | ||
396 | @cindex total size of a window | |
397 | @cindex total window size | |
398 | The following function is the standard interface for getting the total | |
399 | size of any window: | |
400 | ||
401 | @defun window-total-size &optional window &optional horizontal | |
402 | This function returns the total number of lines of @var{window}. The | |
403 | argument @var{window} can denote any window and defaults to the selected | |
404 | one. If @var{window} is live, the return value includes any header or | |
405 | mode lines of @var{window}. If @var{window} is internal, the return | |
406 | value is the sum of the total heights of @var{window}'s child windows | |
407 | provided these are vertically combined and the height of @var{window}'s | |
408 | first child if they are horizontally combined. | |
409 | ||
410 | If the optional argument @var{horizontal} is non-@code{nil}, this | |
411 | function returns the total number of columns of @var{window}. If | |
412 | @var{window} is live, the return value includes any vertical divider | |
413 | column or scroll bars of @var{window}. On a window-system, the return | |
414 | value includes the space occupied by any margins and fringes of | |
415 | @var{window} too. If @var{window} is internal, the return value is the | |
416 | sum of the total widths of @var{window}'s child windows provided these | |
417 | are horizontally combined and the width of @var{window}'s first child | |
418 | otherwise. | |
419 | @end defun | |
420 | ||
421 | Alternatively, the following two functions can be used to retrieve | |
422 | either the total height or the total width of a window: | |
423 | ||
424 | @defun window-total-height &optional window | |
425 | This function returns the total number of lines of @var{window}. | |
426 | @var{window} can be any window and defaults to the selected one. The | |
427 | return value includes @var{window}'s mode line and header line, if any. | |
428 | If @var{window} is internal the return value is the sum of heights of | |
429 | @var{window}'s child windows for a vertical combination and the height | |
430 | of @var{window}'s first child otherwise. | |
431 | @end defun | |
432 | ||
433 | @defun window-total-width &optional window | |
434 | This function returns the total number of columns of @var{window}. | |
435 | @var{window} can be any window and defaults to the selected one. The | |
436 | return value includes any vertical dividers or scrollbars of | |
437 | @var{window}. On a window-system the return value also includes the | |
438 | space occupied by any margins and fringes of @var{window}. If | |
439 | @var{window} is internal, the return value is the sum of the widths of | |
440 | @var{window}'s child windows for a horizontal combination and the width | |
441 | of @var{window}'s first child otherwise. | |
442 | @end defun | |
443 | ||
444 | The total height of any window is usually less than the height of the | |
445 | window's frame, because the latter may also include the minibuffer | |
446 | window. Depending on the toolkit in use, the frame height can also | |
447 | include the menu bar and the tool bar (@pxref{Size and Position}). | |
448 | Therefore, in general it is not straightforward to compare window and | |
449 | frame heights. The following function is useful to determine whether | |
450 | there are no other windows above or below a specified window. | |
451 | ||
452 | @cindex full-height window | |
453 | @defun window-full-height-p &optional window | |
454 | This function returns non-@code{nil} if there is no other window above | |
455 | or below @var{window} on the containing frame. More precisely, this | |
456 | function returns @code{t} if and only if the total height of | |
457 | @var{window} equals the total height of the root window (@pxref{Windows | |
458 | and Frames}) of @var{window}'s frame. The @var{window} argument may | |
459 | denote any window and defaults to the selected one. | |
460 | @end defun | |
461 | ||
462 | @cindex full-width window | |
463 | The following function can be used to determine whether there are no | |
464 | other windows on the left or right of a specified window. | |
465 | ||
466 | @defun window-full-width-p &optional window | |
467 | This function returns non-@code{nil} if there are no other windows on | |
468 | the left or right of @var{window}; @code{nil} otherwise. More | |
469 | precisely, this function returns @code{t} if and only if the total width | |
470 | of @var{window} equals the total width of the root window | |
471 | (@pxref{Windows and Frames}) of @var{window}'s frame. The @var{window} | |
472 | argument may denote any window and defaults to the selected one. | |
473 | @end defun | |
474 | ||
475 | @cindex top line of window | |
476 | @cindex left column of window | |
477 | The windows of a frame are unambiguously characterized by the | |
478 | combination of their top line and left column within that frame. | |
479 | ||
480 | @defun window-top-line &optional window | |
481 | This function returns the top line of @var{window}. The argument | |
482 | @var{window} can denote any window and defaults to the selected one. | |
483 | @end defun | |
484 | ||
485 | @defun window-left-column &optional window | |
486 | This function returns the left column of @var{window}. The argument | |
487 | @var{window} can denote any window and defaults to the selected one. | |
488 | @end defun | |
489 | ||
490 | For a frame displaying one window only, that window's top line and left | |
491 | column are both zero. When a frame displays a window @var{WB} below a | |
492 | window @var{WA}, the top line of @var{WB} can be calculated by adding | |
493 | the total height of @var{WA} to the top line of @var{WA}. When a frame | |
494 | displays a window @var{WR} on the right of a window @var{WL}, the left | |
495 | column of @var{WR} can be calculated by adding the total width of | |
496 | @var{WL} to the left column of @var{WL}. | |
497 | ||
498 | @cindex window body height | |
499 | @cindex body height of a window | |
500 | The @dfn{body height of a window} is specified as the total number of | |
501 | lines occupied by the window's text area. Mode or header lines are not | |
502 | included in a window's body height. | |
503 | ||
504 | @cindex window body width | |
505 | @cindex body width of a window | |
506 | The @dfn{body width of a window} denotes the total number of columns | |
507 | occupied by the window's text area. Scroll bars or columns of @samp{|} | |
508 | characters that separate side-by-side windows are not included in a | |
509 | window's body width. | |
510 | ||
511 | @cindex body size of a window | |
512 | @cindex window body size | |
89bd5ee1 EZ |
513 | @cindex canonical units of window/frame size |
514 | The following functions retrieve height and width of the body of a | |
515 | live window. Note that the values these functions return are measured | |
516 | in @dfn{canonical units}, i.e.@: for the default frame's face. If the | |
517 | window shows some characters with non-default face, e.g., if the font | |
518 | of some characters is larger or smaller than the default font, the | |
519 | values returned by these functions will not match the actual number of | |
520 | lines or characters per line shown in the window. To get the actual | |
521 | number of columns and lines, move to the last character in the line | |
522 | (e.g., with @code{end-of-visual-line}) or to the last line of the | |
523 | window (e.g., with @code{window-end}), and use @code{posn-at-point} to | |
524 | find the line or column there. | |
b33b68a3 MR |
525 | |
526 | @defun window-body-size &optional window horizontal | |
527 | This function returns the number of lines of @var{window}'s text area. | |
528 | @var{window} must be a live window and defaults to the selected one. | |
529 | The return value does not count any mode or header line of @var{window}. | |
530 | ||
531 | Optional argument @var{horizontal} non-@code{nil} means to return the | |
532 | number of columns of @var{window}'s text area. In this case the return | |
533 | value does not include any vertical divider or scroll bar owned by | |
534 | @var{window}. On a window-system the return value does not include the | |
535 | number of columns used for @var{window}'s fringes or display margins | |
536 | either. | |
537 | @end defun | |
538 | ||
539 | @defun window-body-height &optional window | |
540 | This function returns the number of lines of @var{window}'s body. | |
541 | @var{window} must be a live window and defaults to the selected one. | |
542 | ||
543 | The return value does not include @var{window}'s mode line and header | |
544 | line, if any. If a line at the bottom of the window is only partially | |
545 | visible, that line is included in the return value. If you do not | |
546 | want to include a partially visible bottom line in the return value, | |
547 | use @code{window-text-height} instead. | |
548 | @end defun | |
549 | ||
550 | @defun window-body-width &optional window | |
551 | This function returns the number of columns of @var{window}'s body. | |
552 | @var{window} must be a live window and defaults to the selected one. | |
553 | ||
554 | The return value does not include any vertical dividers or scroll bars | |
555 | owned by @var{window}. On a window-system the return value does not | |
556 | include the number of columns used for @var{window}'s fringes or | |
557 | display margins either. | |
558 | @end defun | |
559 | ||
560 | The following functions have been used in earlier versions of Emacs. | |
561 | They are still supported but due to the confusing nomenclature they | |
562 | should not be used any more in future code. | |
563 | ||
564 | @defun window-height &optional window | |
565 | This function is an alias for `window-total-height', see above. | |
566 | @end defun | |
567 | ||
568 | @defun window-width &optional window | |
569 | This function is an alias for `window-body-width', see above. | |
570 | @end defun | |
571 | ||
572 | @cindex minimum window size | |
573 | The following two options constrain the sizes of windows to a minimum | |
574 | height and width. Their values are honored when windows are split | |
575 | (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). Any | |
576 | request to make a window smaller than specified here will usually result | |
577 | in an error. | |
578 | ||
579 | @defopt window-min-height | |
580 | The value of this variable specifies how short a window may be. The | |
581 | value is measured in line units and has to account for any header or | |
582 | mode line. The default value for this option is @code{4}. Values less | |
583 | than @code{1} are ignored. | |
584 | @end defopt | |
585 | ||
586 | @defopt window-min-width | |
587 | The value of this variable specifies how narrow a window may be. The | |
588 | value is measured in characters and includes any margins, fringes, | |
589 | scroll bar and vertical divider column. The default value for this | |
590 | option is @code{10}. A value less than @code{2} is ignored. | |
591 | @end defopt | |
592 | ||
593 | Applications should not rebind these variables. To shrink a specific | |
594 | window to a height or width less than the one specified here, they | |
595 | should rather invoke @code{window-resize} (@pxref{Resizing Windows}) | |
596 | with a non-@code{nil} @var{ignore} argument. The function | |
597 | @code{split-window} (@pxref{Splitting Windows}) can make a window | |
598 | smaller than specified here by calling it with a non-@code{nil} | |
599 | @var{size} argument. Interactively, the values specified here cannot be | |
600 | overridden. | |
601 | ||
602 | Earlier versions of Emacs could delete a window when its size dropped | |
603 | below @code{window-min-height} or @code{window-min-width}. As a rule, | |
604 | the current version of Emacs does no more delete windows by side-effect. | |
605 | The only exception to this rule are requests to resize a frame which may | |
606 | implicitly delete windows when they do not fit on the frame any more, | |
607 | see @ref{Size and Position}. | |
608 | ||
609 | The size of a window can be fixed which means that it cannot be split | |
610 | (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). | |
611 | ||
612 | @cindex fixed-size window | |
613 | @defvar window-size-fixed | |
614 | If this variable is non-@code{nil}, in a given buffer, then the size of | |
615 | any window displaying that buffer remains fixed unless you either | |
616 | explicitly change it or Emacs has no other choice. | |
617 | ||
618 | If the value is @code{height}, then only the window's height is fixed; | |
619 | if the value is @code{width}, then only the window's width is fixed. | |
620 | Any other non-@code{nil} value fixes both the width and the height. | |
621 | ||
622 | This variable automatically becomes buffer-local when set. | |
623 | @end defvar | |
624 | ||
625 | Commands supposed to explicitly change the size of windows such as | |
626 | @code{enlarge-window} (@pxref{Resizing Windows}) get an error if they | |
627 | had to change a window size which is fixed. Other functions like | |
628 | @code{window-resize} (@pxref{Resizing Windows}) have an optional | |
629 | @var{ignore} argument which allows to change the size of fixed-size | |
630 | windows. | |
631 | ||
632 | Deleting a window or changing a frame's size may change the size of a | |
633 | fixed-size window, if there is no other alternative. | |
634 | ||
635 | The height of a vertical combination of windows cannot be changed | |
636 | when the height of all these windows is fixed. Its width cannot be | |
637 | changed if the width of at least one of these windows is fixed. | |
638 | Similarly, the width of a horizontal combination of windows cannot be | |
639 | changed when the width of all these windows is fixed. Its height cannot | |
640 | be changed if the height of at least one of these windows is fixed. | |
641 | ||
642 | The next function allows to check whether the size of an arbitrary | |
643 | window is fixed. | |
644 | ||
645 | @defun window-size-fixed-p &optional window horizontal | |
646 | This function returns non-@code{nil} if @var{window}'s height is fixed. | |
647 | The argument @var{window} can be an arbitrary window and defaults to the | |
648 | selected one. Optional argument @var{horizontal} non-@code{nil} means | |
649 | return non-@code{nil} if @var{window}'s width is fixed. | |
650 | ||
651 | If this function returns @code{nil}, this does not necessarily mean that | |
652 | @var{window} can be resized in the desired direction. The function | |
653 | @code{window-resizable} (@pxref{Resizing Windows}) can tell that. | |
654 | @end defun | |
655 | ||
656 | ||
657 | @node Resizing Windows | |
658 | @section Resizing Windows | |
659 | @cindex window resizing | |
660 | @cindex resize window | |
661 | @cindex changing window size | |
662 | @cindex window size, changing | |
663 | ||
664 | Emacs does not permit overlapping windows or gaps between windows, so | |
665 | changing the size of a window always affects at least one other window. | |
666 | When a frame contains just one window, that window can be resized only | |
667 | by resizing the window's frame. The functions described below are | |
668 | therefore meaningful only in the context of a frame containing at least | |
669 | two windows. The size of the corresponding frame never changes when | |
670 | invoking a function described in this section. | |
671 | ||
672 | The routines changing window sizes always operate in one dimension at | |
673 | a time. This means that windows can be resized only either vertically | |
674 | or horizontally. If a window shall be resized in both dimensions, it | |
675 | must be resized in one dimension first and in the other dimension | |
676 | afterwards. If the second resize operation fails, the frame might end | |
677 | up in an unsatisfactory state. To avoid such states, it might be useful | |
678 | to save the current window configuration (@pxref{Window Configurations}) | |
679 | before attempting the first resize operation and restore the saved | |
680 | configuration in case the second resize operation fails. | |
681 | ||
682 | Functions that resize windows are supposed to obey restrictions | |
683 | imposed by window minimum sizes and fixed-size windows, see @ref{Window | |
684 | Sizes}. In order to determine whether resizing a specific window is | |
685 | possible in the first place, the following function can be used: | |
686 | ||
687 | @defun window-resizable window delta &optional horizontal ignore side noup nodown | |
688 | This function returns @var{delta} if the size of @var{window} can be | |
689 | changed vertically by @var{delta} lines. Optional argument | |
690 | @var{horizontal} non-@code{nil} means to return @var{delta} if | |
691 | @var{window} can be resized horizontally by @var{delta} columns. A | |
692 | return value of zero means that @var{window} is not resizable. | |
693 | ||
694 | If @var{delta} is a positive number, this means that @var{window} shall | |
695 | be enlarged by @var{delta} lines or columns. If @var{window} cannot be | |
696 | enlarged by @var{delta} lines or columns, this function returns the | |
697 | maximum value in the range from 0 to @var{delta} by which @var{window} | |
698 | can be enlarged. | |
699 | ||
700 | If @var{delta} is a negative number, this means that @var{window} shall | |
701 | be shrunk by -@var{delta} lines or columns. If @var{window} cannot be | |
702 | shrunk by -@var{delta} lines or columns, this function returns the | |
703 | minimum value in the range from @var{delta} to 0 that can be used for | |
704 | shrinking @var{window}. | |
705 | ||
706 | Optional argument @var{ignore} non-@code{nil} means ignore any | |
707 | restrictions imposed by the variables @code{window-min-height} or | |
708 | @code{window-min-width} and @code{window-size-fixed}. In this case the | |
709 | minimum height of a window is specified as the minimum number of lines | |
710 | that allow viewing any header or mode line and at least one line of the | |
711 | text area of window. The minimum width of a window includes any | |
712 | fringes, margins and the scroll bar as well as two text columns. | |
713 | ||
714 | If @var{ignore} denotes a window, this means to ignore restrictions for | |
715 | that window only. If @var{ignore} equals the constant @code{safe}, this | |
716 | means a live window may get as small as one line or two columns. | |
717 | ||
718 | Optional argument @var{noup} non-@code{nil} means don't go up in the | |
719 | window tree but try to steal or distribute the space needed for the | |
720 | resize operation among the other windows within @var{window}'s | |
721 | combination. Optional argument @var{nodown} non-@code{nil} means don't | |
be7f5545 | 722 | check whether @var{window} itself and its child windows can be resized. |
b33b68a3 MR |
723 | @end defun |
724 | ||
725 | The function @code{window-resizable} does not change any window sizes. | |
726 | The following function does: | |
727 | ||
728 | @defun window-resize window delta &optional horizontal ignore | |
729 | This function resizes @var{window} vertically by @var{delta} lines. The | |
730 | argument @var{window} can denote an arbitrary window and defaults to the | |
731 | selected one. An attempt to resize the root window of a frame will | |
732 | raise an error. | |
733 | ||
734 | Second argument @var{delta} a positive number means @var{window} shall | |
735 | be enlarged by @var{delta} lines. If @var{delta} is negative, that | |
736 | means @var{window} shall be shrunk by -@var{delta} lines. | |
737 | ||
738 | Optional argument @var{horizontal} non-@code{nil} means to resize | |
739 | @var{window} horizontally by @var{delta} columns. In this case a | |
740 | positive @var{delta} means enlarge @var{window} by @var{delta} columns. | |
741 | A negative @var{delta} means @var{window} shall be shrunk by | |
742 | -@var{delta} columns. | |
743 | ||
744 | Optional argument @var{ignore} has the same meaning as for the function | |
745 | @code{window-resizable} above. | |
746 | ||
747 | This function can simultaneously move two edges of WINDOW. Exactly | |
748 | which edges of @var{window} are moved and which other windows are | |
749 | resized along with @var{window} is determined by the splits and nest | |
750 | status of the involved windows (@pxref{Splitting Windows}). If only the | |
751 | low (right) edge of @var{window} shall be moved, the function | |
752 | @code{adjust-window-trailing-edge} described below should be used. | |
b8d4c8d0 GM |
753 | @end defun |
754 | ||
b33b68a3 MR |
755 | The next four commands are simple interfaces to @code{window-resize}. |
756 | They always operate on the selected window, never delete any window, and | |
757 | always raise an error when resizing would violate a restriction imposed | |
758 | by @code{window-min-height}, @code{window-min-width}, or | |
759 | @code{window-size-fixed}. | |
760 | ||
761 | @deffn Command enlarge-window delta &optional horizontal | |
762 | This function makes the selected window @var{delta} lines taller. | |
763 | Interactively, if no argument is given, it makes the selected window one | |
764 | line taller. If optional argument @var{horizontal} is non-@code{nil}, | |
765 | it makes the selected window wider by @var{delta} columns. If | |
766 | @var{delta} is negative, it shrinks the selected window by -@var{delta} | |
767 | lines or columns. The return value is @code{nil}. | |
768 | @end deffn | |
769 | ||
770 | @deffn Command enlarge-window-horizontally delta | |
771 | This function makes the selected window @var{delta} columns wider. | |
772 | Interactively, if no argument is given, it makes the selected window one | |
773 | column wider. | |
774 | @end deffn | |
775 | ||
776 | @deffn Command shrink-window delta &optional horizontal | |
777 | This function makes the selected window @var{delta} lines smaller. | |
778 | Interactively, if no argument is given, it makes the selected window one | |
779 | line smaller. If optional argument @var{horizontal} is non-@code{nil}, | |
780 | it makes the selected window narrower by @var{delta} columns. If | |
781 | @var{delta} is negative, it enlarges the selected window by -@var{delta} | |
782 | lines or columns. The return value is @code{nil}. | |
783 | @end deffn | |
784 | ||
785 | @deffn Command shrink-window-horizontally delta | |
786 | This function makes the selected window @var{delta} columns narrower. | |
787 | Interactively, if no argument is given, it makes the selected window one | |
788 | column narrower. | |
789 | @end deffn | |
790 | ||
791 | The following function is useful for moving the line dividing two | |
792 | windows. | |
793 | ||
794 | @defun adjust-window-trailing-edge window delta &optional horizontal | |
795 | This function moves @var{window}'s bottom edge by @var{delta} lines. | |
796 | Optional argument @var{horizontal} non-@code{nil} means to move | |
797 | @var{window}'s right edge by @var{delta} columns. The argument | |
798 | @var{window} defaults to the selected window. | |
799 | ||
800 | If @var{delta} is greater zero, this moves the edge downwards or to the | |
801 | right. If @var{delta} is less than zero, this moves the edge upwards or | |
802 | to the left. If the edge can't be moved by @var{delta} lines or columns, | |
803 | it is moved as far as possible in the desired direction but no error is | |
804 | signalled. | |
805 | ||
806 | This function tries to resize windows adjacent to the edge that is | |
807 | moved. Only if this is insufficient, it will also resize windows not | |
808 | adjacent to that edge. As a consequence, if you move an edge in one | |
809 | direction and back in the other direction by the same amount, the | |
810 | resulting window configuration will not be necessarily identical to the | |
811 | one before the first move. So if your intend to just resize | |
812 | @var{window}, you should not use this function but call | |
813 | @code{window-resize} (see above) instead. | |
814 | @end defun | |
815 | ||
816 | @deffn Command fit-window-to-buffer &optional window max-height min-height override | |
817 | This command makes @var{window} the right height to display its | |
818 | contents exactly. The default for @var{window} is the selected window. | |
819 | ||
820 | The optional argument @var{max-height} specifies the maximum total | |
821 | height the window is allowed to be; @code{nil} means use the maximum | |
822 | permissible height of a window on @var{window}'s frame. The optional | |
823 | argument @var{min-height} specifies the minimum toatl height for the | |
824 | window; @code{nil} means use @code{window-min-height}. All these height | |
825 | values include the mode line and/or header line. | |
826 | ||
827 | If the optional argument @var{override} is non-@code{nil}, this means to | |
828 | ignore any restrictions imposed by @code{window-min-height} and | |
829 | @code{window-min-width} on the size of @var{window}. | |
830 | ||
831 | This function returns non-@code{nil} if it orderly resized @var{window}, | |
832 | and @code{nil} otherwise. | |
833 | @end deffn | |
834 | ||
835 | @deffn Command shrink-window-if-larger-than-buffer &optional window | |
836 | This command shrinks @var{window} vertically to be as small as possible | |
837 | while still showing the full contents of its buffer---but not less than | |
838 | @code{window-min-height} lines. The argument @var{window} must denote | |
839 | a live window and defaults to the selected one. | |
840 | ||
841 | However, this command does nothing if the window is already too small to | |
842 | display the whole text of the buffer, or if part of the contents are | |
843 | currently scrolled off screen, or if the window is not the full width of | |
844 | its frame, or if the window is the only window in its frame. | |
845 | ||
846 | This command returns non-@code{nil} if it actually shrank the window | |
847 | and @code{nil} otherwise. | |
848 | @end deffn | |
849 | ||
850 | @cindex balancing window sizes | |
851 | Emacs provides two functions to balance windows, that is, to even out | |
852 | the sizes of all windows on the same frame. The minibuffer window and | |
853 | fixed-size windows are not resized by these functions. | |
854 | ||
855 | @deffn Command balance-windows &optional window-or-frame | |
856 | This function balances windows in a way that gives more space to | |
857 | full-width and/or full-height windows. If @var{window-or-frame} | |
858 | specifies a frame, it balances all windows on that frame. If | |
859 | @var{window-or-frame} specifies a window, it balances that window and | |
860 | its siblings (@pxref{Windows and Frames}) only. | |
861 | @end deffn | |
862 | ||
863 | @deffn Command balance-windows-area | |
864 | This function attempts to give all windows on the selected frame | |
865 | approximately the same share of the screen area. This means that | |
866 | full-width or full-height windows are not given more space than other | |
867 | windows. | |
868 | @end deffn | |
869 | ||
870 | @cindex maximizing windows | |
871 | The following function can be used to give a window the maximum possible | |
872 | size without deleting other ones. | |
873 | ||
874 | @deffn Command maximize-window &optional window | |
875 | This function maximizes @var{window}. More precisely, this makes | |
876 | @var{window} as large as possible without resizing its frame or deleting | |
877 | other windows. @var{window} can be any window and defaults to the | |
878 | selected one. | |
879 | @end deffn | |
880 | ||
881 | @cindex minimizing windows | |
882 | To make a window as small as possible without deleting it the | |
883 | following function can be used. | |
884 | ||
885 | @deffn Command minimize-window &optional window | |
886 | This function minimizes @var{window}. More precisely, this makes | |
887 | @var{window} as small as possible without deleting it or resizing its | |
888 | frame. @var{window} can be any window and defaults to the selected one. | |
889 | @end deffn | |
890 | ||
891 | ||
b8d4c8d0 GM |
892 | @node Splitting Windows |
893 | @section Splitting Windows | |
894 | @cindex splitting windows | |
895 | @cindex window splitting | |
896 | ||
b33b68a3 MR |
897 | The functions described below are the primitives needed for creating a |
898 | new window. They do not accept a buffer as an argument. Rather, they | |
899 | ``split'' an existing window into two halves, both displaying the buffer | |
b8d4c8d0 GM |
900 | previously visible in the window that was split. |
901 | ||
b33b68a3 MR |
902 | @deffn Command split-window &optional window size side |
903 | This function creates a new window adjacent to @var{window}. It returns | |
904 | the new window which is always a live window. The argument @var{window} | |
905 | can denote any window and defaults to the selected one. This function | |
906 | does not change the selected window. | |
907 | ||
908 | Optional second argument @var{size} a positive number means make | |
909 | @var{window} @var{size} lines (or columns) tall. If @var{size} is | |
910 | negative, make the new window @minus{}@var{size} lines (or columns) | |
911 | tall. If @var{size} is omitted or @code{nil}, then @var{window} is | |
912 | divided evenly into two parts. (If there is an odd line, it is | |
913 | allocated to the new window.) | |
914 | ||
915 | If splitting would result in making a window smaller than | |
916 | @code{window-min-height} or @code{window-min-width} (@pxref{Window | |
917 | Sizes}), this function usually signals an error. However, if @var{size} | |
918 | is non-@code{nil} and valid, a new window of the requested size is | |
919 | created. (A size value would be invalid if it assigned less than one | |
920 | line or less than two columns to the new window.) | |
921 | ||
922 | Optional third argument @var{side} @code{nil} (or @code{below}) | |
923 | specifies that the new window shall be located below @var{window}. The | |
924 | value @code{above} means the new window will be located above | |
925 | @var{window}. In both cases @var{size} specifies the new number of | |
926 | lines for @var{window} (or the new window if @var{size} is negative) | |
927 | including space reserved for the mode and/or header line. | |
928 | ||
929 | If @var{side} is @code{t} or @code{right} the new window will be | |
930 | positioned on the right side of @var{window}. The value @code{left} | |
931 | means the new window will be located on the left side of @var{window}. | |
932 | In both cases @var{size} specifies the new number of columns for | |
933 | @var{window} (or the new window provided @var{size} is negative) | |
934 | including space reserved for margins, fringes and the scroll bar or a | |
935 | divider column. | |
936 | ||
937 | Any other non-@code{nil} value for @var{side} is currently handled like | |
938 | @code{t} (or @code{right}). Since this might change in the future, | |
939 | application programs should refrain from using other values. | |
940 | ||
941 | If @var{window} is live, properties of the new window like margins and | |
942 | scroll bars are inherited from @var{window}. If @var{window} is an | |
943 | internal window, these properties, as well as the buffer shown in the | |
944 | new window, are inherited from the window selected on @var{window}'s | |
945 | frame. | |
946 | ||
947 | If @code{ignore-window-parameters} is non-@code{nil}, this function | |
948 | ignores window parameters (@pxref{Window Parameters}). Otherwise, if | |
949 | the @code{split-window} parameter of @var{window} is @code{t}, it splits | |
950 | the window disregarding any other window parameters. If the | |
951 | @code{split-window} parameter specifies a function, that function is | |
952 | called with the arguments @var{window}, @var{size}, and @var{side} to | |
953 | split @var{window}. If that function is @code{ignore}, nothing is done. | |
954 | @end deffn | |
b8d4c8d0 GM |
955 | |
956 | The following example starts with one window on a screen that is 50 | |
957 | lines high by 80 columns wide; then it splits the window. | |
958 | ||
959 | @smallexample | |
960 | @group | |
b33b68a3 | 961 | (setq W1 (selected-window)) |
b8d4c8d0 | 962 | @result{} #<window 8 on windows.texi> |
b33b68a3 | 963 | (setq W2 (split-window W1 15)) |
b8d4c8d0 GM |
964 | @result{} #<window 28 on windows.texi> |
965 | @end group | |
966 | @group | |
b33b68a3 MR |
967 | (window-top-line W1) |
968 | @result{} 0 | |
969 | (window-total-size W1) | |
970 | @result{} 15 | |
971 | (window-top-line W2) | |
972 | @result{} 15 | |
b8d4c8d0 GM |
973 | @end group |
974 | @end smallexample | |
975 | ||
976 | The screen looks like this: | |
977 | ||
978 | @smallexample | |
979 | @group | |
980 | __________ | |
981 | | | line 0 | |
b33b68a3 | 982 | | W1 | |
b8d4c8d0 GM |
983 | |__________| |
984 | | | line 15 | |
b33b68a3 | 985 | | W2 | |
b8d4c8d0 GM |
986 | |__________| |
987 | line 50 | |
988 | column 0 column 80 | |
989 | @end group | |
990 | @end smallexample | |
991 | ||
b33b68a3 | 992 | Next, split the top window into two side-by-side windows: |
b8d4c8d0 GM |
993 | |
994 | @smallexample | |
995 | @group | |
b33b68a3 | 996 | (setq W3 (split-window W1 35 t)) |
b8d4c8d0 GM |
997 | @result{} #<window 32 on windows.texi> |
998 | @end group | |
999 | @group | |
b33b68a3 MR |
1000 | (window-left-column W1) |
1001 | @result{} 0 | |
1002 | (window-total-size W1 t) | |
1003 | @result{} 35 | |
1004 | (window-left-column W3) | |
1005 | @result{} 35 | |
b8d4c8d0 GM |
1006 | @end group |
1007 | @end smallexample | |
1008 | ||
1009 | @need 3000 | |
1010 | Now the screen looks like this: | |
1011 | ||
1012 | @smallexample | |
1013 | @group | |
1014 | column 35 | |
1015 | __________ | |
b33b68a3 MR |
1016 | | | | line 0 |
1017 | | W1 | W3 | | |
1018 | |____|_____| | |
b8d4c8d0 | 1019 | | | line 15 |
b33b68a3 | 1020 | | W2 | |
b8d4c8d0 GM |
1021 | |__________| |
1022 | line 50 | |
1023 | column 0 column 80 | |
1024 | @end group | |
1025 | @end smallexample | |
1026 | ||
1027 | Normally, Emacs indicates the border between two side-by-side windows | |
a1401ab1 EZ |
1028 | with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The |
1029 | display table can specify alternative border characters; see @ref{Display | |
0273ca3a | 1030 | Tables}. |
b8d4c8d0 | 1031 | |
b33b68a3 MR |
1032 | Below we describe how @code{split-window} can be used to create the |
1033 | window configuration from our earlier example (@pxref{Windows and | |
1034 | Frames}) and how internal windows are created for this purpose. We | |
1035 | start with a frame containing one live window @code{W2} (in the | |
1036 | following scenarios window names are assigned in an arbitrary manner in | |
1037 | order to match the names of the example). Evaluating the form | |
1038 | @code{(split-window W2 8 t)} creates a new internal window @code{W1} | |
1039 | with two children---@code{W2} (the window we've split) and a new leaf | |
1040 | window @code{W6}: | |
1041 | @smallexample | |
1042 | @group | |
1043 | ______________________________________ | |
1044 | | ______ ____________________________ | | |
1045 | || || || | |
1046 | || || || | |
1047 | || || || | |
1048 | || || || | |
1049 | || || || | |
1050 | || || || | |
1051 | || || || | |
1052 | || || || | |
1053 | || || || | |
1054 | || || || | |
1055 | ||__W2__||_____________W6_____________ | | |
1056 | |__________________W1__________________| | |
1057 | ||
1058 | @end group | |
1059 | @end smallexample | |
1060 | ||
1061 | Evaluating now @code{(split-window W6 -3)} creates another internal | |
1062 | window @code{W3} with two children---@code{W6} and a new live window | |
1063 | @code{W5}. This leaves us with a vertically combined window @code{W3} | |
1064 | embedded in the horizontally combined window @code{W1}: | |
1065 | @smallexample | |
1066 | @group | |
1067 | ______________________________________ | |
1068 | | ______ ____________________________ | | |
1069 | || || __________________________ || | |
1070 | || ||| ||| | |
1071 | || ||| ||| | |
1072 | || ||| ||| | |
1073 | || ||| ||| | |
1074 | || ||| ||| | |
1075 | || |||____________W6____________||| | |
1076 | || || __________________________ || | |
1077 | || ||| ||| | |
1078 | || |||____________W5____________||| | |
1079 | ||__W2__||_____________W3_____________ | | |
1080 | |__________________W1__________________| | |
1081 | ||
1082 | @end group | |
1083 | @end smallexample | |
1084 | ||
1085 | Finally, evaluating @code{(split-window W6 nil t)} should get us the | |
1086 | desired configuration as depicted below. | |
1087 | @smallexample | |
1088 | @group | |
1089 | ______________________________________ | |
1090 | | ______ ____________________________ | | |
1091 | || || __________________________ || | |
1092 | || ||| ___________ ___________ ||| | |
1093 | || |||| || |||| | |
1094 | || |||| || |||| | |
1095 | || ||||_____W6____||_____W7____|||| | |
1096 | || |||____________W4____________||| | |
1097 | || || __________________________ || | |
1098 | || ||| ||| | |
1099 | || |||____________W5____________||| | |
1100 | ||__W2__||_____________W3_____________ | | |
1101 | |__________________W1__________________| | |
1102 | ||
1103 | @end group | |
1104 | @end smallexample | |
1105 | ||
1106 | The scenario sketched above is the standard way to obtain the desired | |
1107 | configuration. In Emacs 23 it was also the only way to do that since | |
1108 | Emacs 23 did't allow splitting internal windows. | |
1109 | ||
1110 | With Emacs 24 you can also proceed as follows: Split an initial window | |
1111 | @code{W6} by evaluating @code{(split-window W6 -3)} to produce the | |
1112 | following vertical combination: | |
1113 | @smallexample | |
1114 | @group | |
1115 | ______________________________________ | |
1116 | | ____________________________________ | | |
1117 | || || | |
1118 | || || | |
1119 | || || | |
1120 | || || | |
1121 | || || | |
1122 | || || | |
1123 | || || | |
1124 | ||_________________W6_________________|| | |
1125 | | ____________________________________ | | |
1126 | || || | |
1127 | ||_________________W5_________________|| | |
1128 | |__________________W3__________________| | |
1129 | ||
1130 | @end group | |
1131 | @end smallexample | |
1132 | ||
1133 | Evaluating now @code{(split-window (window-parent W6) -8 'left)} or, | |
1134 | equivalently, @code{(split-window W3 -8 'left)} should now produce the | |
1135 | penultimate configuration from the previous scenario from where we can | |
1136 | continue as described before. | |
1137 | ||
a239d4e9 | 1138 | Another strategy starts with splitting an initial window @code{W6} by |
b33b68a3 MR |
1139 | evaluating @code{(split-window W6 nil nil t)} with the following result: |
1140 | @smallexample | |
1141 | @group | |
1142 | ______________________________________ | |
1143 | | _________________ _________________ | | |
1144 | || || || | |
1145 | || || || | |
1146 | || || || | |
1147 | || || || | |
1148 | || || || | |
1149 | || || || | |
1150 | || || || | |
1151 | || || || | |
1152 | || || || | |
1153 | || || || | |
1154 | ||________W6_______||________W7_______|| | |
1155 | |__________________W4__________________| | |
1156 | ||
1157 | @end group | |
1158 | @end smallexample | |
1159 | ||
1160 | Evaluating now @code{(split-window W4 -3)} or @code{(split-window | |
1161 | (window-parent W6) -3)} should get us a configuration as shown next. | |
1162 | @smallexample | |
1163 | @group | |
1164 | ______________________________________ | |
1165 | | ____________________________________ | | |
1166 | || ________________ ________________ || | |
1167 | ||| || ||| | |
1168 | ||| || ||| | |
1169 | ||| || ||| | |
1170 | ||| || ||| | |
1171 | ||| || ||| | |
1172 | |||_______W6_______||________W7______||| | |
1173 | ||_________________W4_________________|| | |
1174 | | ____________________________________ | | |
1175 | || || | |
1176 | ||_________________W5_________________|| | |
1177 | |__________________W3__________________| | |
1178 | ||
1179 | @end group | |
1180 | @end smallexample | |
1181 | ||
1182 | The desired configuration can be now obtained by evaluating | |
1183 | @code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window | |
1184 | (window-parent W5) -8 'left)}. | |
1185 | ||
1186 | For a final approach let's start with the configuration of two live | |
1187 | windows @code{W6} and @code{W7} shown above. If we now evaluate | |
1188 | @code{(split-window W4 -8 'left)} or @code{(split-window (window-parent | |
1189 | W6) -8 'left)} we get the following configuration. | |
1190 | @smallexample | |
1191 | @group | |
1192 | ______________________________________ | |
1193 | | ______ ____________________________ | | |
1194 | || || ____________ ____________ || | |
1195 | || ||| || ||| | |
1196 | || ||| || ||| | |
1197 | || ||| || ||| | |
1198 | || ||| || ||| | |
1199 | || ||| || ||| | |
1200 | || ||| || ||| | |
1201 | || ||| || ||| | |
1202 | || |||______W6____||______W7____||| | |
1203 | ||__W2__||_____________W4_____________|| | |
1204 | |__________________W1__________________| | |
1205 | ||
1206 | @end group | |
1207 | @end smallexample | |
1208 | ||
1209 | Evaluating now @code{(split-window W4 -3)} or, for example, | |
1210 | @code{(split-window (window-parent W6) -3)} should produce the desired | |
1211 | configuration. | |
1212 | ||
1213 | The two options described next can be used to tune the operation of | |
1214 | @code{split-window}. | |
1215 | ||
1216 | @defopt window-splits | |
1217 | If this variable is nil, the function @code{split-window} can split a | |
1218 | window if and only if that window's screen estate is sufficiently large | |
a239d4e9 | 1219 | to accommodate both--itself and the new window. |
b33b68a3 MR |
1220 | |
1221 | If this variable is non-@code{nil}, @code{split-window} tries to resize | |
1222 | all windows that are part of the same combination as the old window to | |
a239d4e9 | 1223 | accommodate the new window. Hence, the new window can be also created if |
b33b68a3 MR |
1224 | the old window is of fixed size or too small to split (@pxref{Window |
1225 | Sizes}). | |
1226 | ||
1227 | In any case, the value of this variable is assigned to the splits status | |
1228 | of the new window and, provided old and new window form a new | |
1229 | combination, of the old window as well. The splits status of a window | |
1230 | can be retrieved by invoking the function @code{window-splits} and | |
1231 | altered by the function @code{set-window-splits} described next. | |
1232 | ||
1233 | If @code{window-nest} (see below) is non-@code{nil}, the space for the | |
1234 | new window is exclusively taken from the old window, but the splits | |
1235 | status of the involved windows is nevertheless set as described here. | |
1236 | @end defopt | |
1237 | ||
1238 | @defun window-splits &optional window | |
1239 | This function returns the splits status of @var{window}. The argument | |
1240 | @var{window} can be any window and defaults to the selected one. | |
1241 | ||
1242 | @cindex splits status | |
1243 | The @dfn{splits status} of a window specifies how resizing and deleting | |
1244 | that window may affect the size of other windows in the same window | |
1245 | combination. More precisely, if @var{window}'s splits status is | |
1246 | @code{nil} and @var{window} is resized, the corresponding space is | |
1247 | preferably taken from (or given to) @var{window}'s right sibling. When | |
1248 | @var{window} is deleted, its space is given to its left sibling. If | |
1249 | @var{window}'s splits status is non-@code{nil}, resizing and deleting | |
1250 | @var{window} may resize @emph{all} windows in @var{window}'s | |
1251 | combination. | |
1252 | ||
1253 | The splits status is initially set by @code{split-window} | |
1254 | from the current value of the variable @code{window-splits} (see above) | |
1255 | and can be reset by the function @code{set-window-splits} (see below). | |
1256 | @end defun | |
1257 | ||
1258 | @defun set-window-splits window &optional status | |
1259 | This function sets the splits status (see above) of @var{window} to | |
1260 | @var{status}. The argument @var{window} can be any window and defaults | |
1261 | to the selected one. The return value is @var{status}. | |
1262 | @end defun | |
1263 | ||
1264 | To illustrate the use of @code{window-splits} consider the following | |
1265 | window configuration: | |
1266 | @smallexample | |
1267 | @group | |
1268 | ______________________________________ | |
1269 | | ____________________________________ | | |
1270 | || || | |
1271 | || || | |
1272 | || || | |
1273 | || || | |
1274 | ||_________________W2_________________|| | |
1275 | | ____________________________________ | | |
1276 | || || | |
1277 | || || | |
1278 | || || | |
1279 | || || | |
1280 | ||_________________W3_________________|| | |
1281 | |__________________W1__________________| | |
1282 | ||
1283 | @end group | |
1284 | @end smallexample | |
1285 | ||
1286 | Splitting window @code{W3} with @code{window-splits} @code{nil} | |
1287 | produces a configuration where the size of @code{W2} remains unchanged: | |
1288 | @smallexample | |
1289 | @group | |
1290 | ______________________________________ | |
1291 | | ____________________________________ | | |
1292 | || || | |
1293 | || || | |
1294 | || || | |
1295 | || || | |
1296 | ||_________________W2_________________|| | |
1297 | | ____________________________________ | | |
1298 | || || | |
1299 | ||_________________W3_________________|| | |
1300 | | ____________________________________ | | |
1301 | || || | |
1302 | ||_________________W4_________________|| | |
1303 | |__________________W1__________________| | |
1304 | ||
1305 | @end group | |
1306 | @end smallexample | |
1307 | ||
1308 | Splitting @code{W3} with @code{window-splits} non-@code{nil} instead | |
1309 | produces a configuration where all windows have approximately the same | |
1310 | height: | |
1311 | ||
1312 | @smallexample | |
1313 | @group | |
1314 | ______________________________________ | |
1315 | | ____________________________________ | | |
1316 | || || | |
1317 | || || | |
1318 | ||_________________W2_________________|| | |
1319 | | ____________________________________ | | |
1320 | || || | |
1321 | || || | |
1322 | ||_________________W3_________________|| | |
1323 | | ____________________________________ | | |
1324 | || || | |
1325 | || || | |
1326 | ||_________________W4_________________|| | |
1327 | |__________________W1__________________| | |
1328 | ||
1329 | @end group | |
1330 | @end smallexample | |
1331 | ||
1332 | @defopt window-nest | |
1333 | If this variable is @code{nil}, @code{split-window} creates a new parent | |
1334 | window if and only if the old window has no parent window or shall be | |
1335 | split orthogonally to the combination it is part of. If this variable | |
1336 | is non-@code{nil}, @code{split-window} always creates a new parent | |
1337 | window. If this variable is always non-@code{nil}, a frame's window | |
1338 | tree is a binary tree so every window but the frame's root window has | |
1339 | exactly one sibling. | |
1340 | ||
1341 | The value of this variable is also assigned to the nest status of the | |
1342 | new parent window. The nest status of any window can be retrieved via | |
1343 | the function @code{window-nest} and altered by the function | |
1344 | @code{set-window-nest}, see below. | |
1345 | @end defopt | |
1346 | ||
1347 | @defun window-nest &optional window | |
1348 | This function returns the nest status of @var{window}. The argument | |
1349 | @var{window} can be any window and defaults to the selected one. Note, | |
1350 | however, that the nest status is currently meaningful for internal | |
1351 | windows only. | |
1352 | ||
1353 | @cindex nest status | |
1354 | The @dfn{nest status} of a window specifies whether that window may be | |
be7f5545 MR |
1355 | removed and its child windows recombined with that window's siblings |
1356 | when such a sibling's child window is deleted. The nest status is | |
1357 | initially assigned by @code{split-window} from the current value of the | |
1358 | variable @code{window-nest} (see above) and can be reset by the function | |
b33b68a3 MR |
1359 | @code{set-window-nest} (see below). |
1360 | ||
be7f5545 | 1361 | If the return value is @code{nil}, child windows of @var{window} may be |
b33b68a3 | 1362 | recombined with @var{window}'s siblings when a window gets deleted. A |
be7f5545 | 1363 | return value of @code{nil} means that child windows of @var{window} are |
b33b68a3 MR |
1364 | never (re-)combined with @var{window}'s siblings in such a case. |
1365 | @end defun | |
1366 | ||
1367 | @defun set-window-nest window &optional status | |
1368 | This functions sets the nest status (see above) of @var{window} to | |
1369 | @var{status}. The argument @var{window} can be any window and defaults | |
1370 | to the selected one. Note that setting the nest status is meaningful | |
1371 | for internal windows only. The return value is @var{status}. | |
1372 | @end defun | |
1373 | ||
1374 | To illustrate the use of @code{window-nest} consider the following | |
1375 | configuration (throughout the following examples we shall assume that | |
1376 | @code{window-splits} invariantly is @code{nil}). | |
1377 | @smallexample | |
1378 | @group | |
1379 | ______________________________________ | |
1380 | | ____________________________________ | | |
1381 | || || | |
1382 | || || | |
1383 | || || | |
1384 | || || | |
1385 | || || | |
1386 | || || | |
1387 | ||_________________W2_________________|| | |
1388 | | ____________________________________ | | |
1389 | || || | |
1390 | || || | |
1391 | ||_________________W3_________________|| | |
1392 | |__________________W1__________________| | |
1393 | ||
1394 | @end group | |
1395 | @end smallexample | |
1396 | ||
1397 | Splitting @code{W2} into two windows above each other with | |
1398 | @code{window-nest} equal @code{nil} will get you a configuration like: | |
1399 | @smallexample | |
1400 | @group | |
1401 | ______________________________________ | |
1402 | | ____________________________________ | | |
1403 | || || | |
1404 | || || | |
1405 | ||_________________W2_________________|| | |
1406 | | ____________________________________ | | |
1407 | || || | |
1408 | || || | |
1409 | ||_________________W4_________________|| | |
1410 | | ____________________________________ | | |
1411 | || || | |
1412 | || || | |
1413 | ||_________________W3_________________|| | |
1414 | |__________________W1__________________| | |
1415 | ||
1416 | @end group | |
1417 | @end smallexample | |
1418 | ||
1419 | If you now enlarge window @code{W4}, Emacs steals the necessary space | |
1420 | from window @code{W3} resulting in a configuration like: | |
1421 | @smallexample | |
1422 | @group | |
1423 | ______________________________________ | |
1424 | | ____________________________________ | | |
1425 | || || | |
1426 | || || | |
1427 | ||_________________W2_________________|| | |
1428 | | ____________________________________ | | |
1429 | || || | |
1430 | || || | |
1431 | || || | |
1432 | ||_________________W4_________________|| | |
1433 | | ____________________________________ | | |
1434 | || || | |
1435 | ||_________________W3_________________|| | |
1436 | |__________________W1__________________| | |
1437 | ||
1438 | @end group | |
1439 | @end smallexample | |
1440 | ||
1441 | Deleting window @code{W4}, will return its space to @code{W2} as | |
1442 | follows: | |
1443 | @smallexample | |
1444 | @group | |
1445 | ______________________________________ | |
1446 | | ____________________________________ | | |
1447 | || || | |
1448 | || || | |
1449 | || || | |
1450 | || || | |
1451 | || || | |
1452 | || || | |
1453 | || || | |
1454 | ||_________________W2_________________|| | |
1455 | | ____________________________________ | | |
1456 | || || | |
1457 | ||_________________W3_________________|| | |
1458 | |__________________W1__________________| | |
1459 | ||
1460 | @end group | |
1461 | @end smallexample | |
1462 | ||
1463 | Hence, with respect to the initial configuration, window @code{W2} has | |
1464 | grown at the expense of window @code{W3}. If, however, in the initial | |
1465 | configuration you had split @code{W2} with @code{window-nest} bound to | |
1466 | @code{t}, a new internal window @code{W5} would have been created as | |
1467 | depicted below. | |
1468 | @smallexample | |
1469 | @group | |
1470 | ______________________________________ | |
1471 | | ____________________________________ | | |
1472 | || __________________________________ || | |
1473 | ||| ||| | |
1474 | |||________________W2________________||| | |
1475 | || __________________________________ || | |
1476 | ||| ||| | |
1477 | |||________________W4________________||| | |
1478 | ||_________________W5_________________|| | |
1479 | | ____________________________________ | | |
1480 | || || | |
1481 | || || | |
1482 | ||_________________W3_________________|| | |
1483 | |__________________W1__________________| | |
1484 | ||
1485 | @end group | |
1486 | @end smallexample | |
1487 | ||
1488 | Enlarging @code{W4} would now have stolen the necessary space from | |
1489 | @code{W2} instead of @code{W3} as | |
1490 | @smallexample | |
1491 | @group | |
1492 | ______________________________________ | |
1493 | | ____________________________________ | | |
1494 | || __________________________________ || | |
1495 | |||________________W2________________||| | |
1496 | || __________________________________ || | |
1497 | ||| ||| | |
1498 | ||| ||| | |
1499 | |||________________W4________________||| | |
1500 | ||_________________W5_________________|| | |
1501 | | ____________________________________ | | |
1502 | || || | |
1503 | || || | |
1504 | ||_________________W3_________________|| | |
1505 | |__________________W1__________________| | |
1506 | ||
1507 | @end group | |
1508 | @end smallexample | |
1509 | ||
1510 | and the subsequent deletion of @code{W4} would have restored the initial | |
1511 | configuration. | |
1512 | ||
1513 | For interactive use, Emacs provides two commands which always split the | |
1514 | selected window. | |
1515 | ||
291d142b | 1516 | @deffn Command split-window-below &optional size |
b8d4c8d0 GM |
1517 | This function splits the selected window into two windows, one above the |
1518 | other, leaving the upper of the two windows selected, with @var{size} | |
1519 | lines. (If @var{size} is negative, then the lower of the two windows | |
96995b89 | 1520 | gets @minus{}@var{size} lines and the upper window gets the rest, but |
b8d4c8d0 GM |
1521 | the upper window is still the one selected.) However, if |
1522 | @code{split-window-keep-point} (see below) is @code{nil}, then either | |
1523 | window can be selected. | |
1524 | ||
b33b68a3 MR |
1525 | In other respects, this function is similar to @code{split-window}. |
1526 | In particular, the upper window is the original one and the return value | |
1527 | is the new, lower window. | |
b8d4c8d0 GM |
1528 | @end deffn |
1529 | ||
1530 | @defopt split-window-keep-point | |
1531 | If this variable is non-@code{nil} (the default), then | |
291d142b | 1532 | @code{split-window-below} behaves as described above. |
b8d4c8d0 | 1533 | |
291d142b CY |
1534 | If it is @code{nil}, then @code{split-window-below} adjusts point |
1535 | in each of the two windows to avoid scrolling. (This is useful on | |
1536 | slow terminals.) It selects whichever window contains the screen line | |
1537 | that point was previously on. Other functions are not affected by | |
1538 | this variable. | |
b8d4c8d0 GM |
1539 | @end defopt |
1540 | ||
291d142b | 1541 | @deffn Command split-window-right &optional size |
b8d4c8d0 GM |
1542 | This function splits the selected window into two windows |
1543 | side-by-side, leaving the selected window on the left with @var{size} | |
1544 | columns. If @var{size} is negative, the rightmost window gets | |
96995b89 | 1545 | @minus{}@var{size} columns, but the leftmost window still remains |
b8d4c8d0 | 1546 | selected. |
b8d4c8d0 GM |
1547 | @end deffn |
1548 | ||
b8d4c8d0 GM |
1549 | |
1550 | @node Deleting Windows | |
1551 | @section Deleting Windows | |
1552 | @cindex deleting windows | |
1553 | ||
1554 | A window remains visible on its frame unless you @dfn{delete} it by | |
1555 | calling certain functions that delete windows. A deleted window cannot | |
1556 | appear on the screen, but continues to exist as a Lisp object until | |
1557 | there are no references to it. There is no way to cancel the deletion | |
1558 | of a window aside from restoring a saved window configuration | |
1559 | (@pxref{Window Configurations}). Restoring a window configuration also | |
b33b68a3 MR |
1560 | deletes any windows that aren't part of that configuration. Erroneous |
1561 | information may result from using a deleted window as if it were live. | |
b8d4c8d0 GM |
1562 | |
1563 | @deffn Command delete-window &optional window | |
0273ca3a | 1564 | This function removes @var{window} from display and returns @code{nil}. |
b33b68a3 MR |
1565 | The argument @var{window} can denote any window and defaults to the |
1566 | selected one. An error is signaled if @var{window} is the only window | |
1567 | on its frame. Hence @var{window} must have at least one sibling window | |
c72063fa MR |
1568 | (@pxref{Windows and Frames}) in order to get deleted. If @var{window} |
1569 | is the selected window on its frame, this function selects the most | |
1570 | recently selected live window on that frame instead. | |
b33b68a3 MR |
1571 | |
1572 | If the variable @code{ignore-window-parameters} (@pxref{Window | |
1573 | Parameters}) is non-@code{nil}, this function ignores all parameters of | |
1574 | @var{window}. Otherwise, if the @code{delete-window} parameter of | |
1575 | @var{window} is @code{t}, it deletes the window disregarding other | |
1576 | window parameters. If the @code{delete-window} parameter specifies a | |
1577 | function, that function is called with @var{window} as its sole | |
1578 | argument. | |
1579 | ||
1580 | If the splits status of @var{window} (@pxref{Splitting Windows}) is | |
1581 | @code{nil}, the space @var{window} took up is given to its left sibling | |
1582 | if such a window exists and to its right sibling otherwise. If the | |
1583 | splits status of @var{window} is non-@code{nil}, its space is | |
1584 | proportionally distributed among the remaining windows in the same | |
1585 | combination. | |
b8d4c8d0 GM |
1586 | @end deffn |
1587 | ||
1588 | @deffn Command delete-other-windows &optional window | |
b33b68a3 MR |
1589 | This function makes @var{window} fill its frame and returns @code{nil}. |
1590 | The argument @var{window} can denote an arbitrary window and defaults to | |
c72063fa MR |
1591 | the selected one. Upon exit, @var{window} will be the selected window |
1592 | on its frame. | |
b33b68a3 MR |
1593 | |
1594 | If the variable @code{ignore-window-parameters} (@pxref{Window | |
1595 | Parameters}) is non-@code{nil}, this function ignores all parameters of | |
1596 | @var{window}. Otherwise, if the @code{delete-other-windows} parameter | |
1597 | of @var{window} equals @code{t}, it deletes all other windows | |
1598 | disregarding any remaining window parameters. If the | |
1599 | @code{delete-other-windows} parameter of @var{window} specifies a | |
1600 | function, it calls that function with @var{window} as its sole argument. | |
b8d4c8d0 GM |
1601 | @end deffn |
1602 | ||
520b29e7 | 1603 | @deffn Command delete-windows-on &optional buffer-or-name frame |
b33b68a3 MR |
1604 | This function deletes all windows showing @var{buffer-or-name} and |
1605 | returns nil. If there are no windows showing @var{buffer-or-name}, it | |
1606 | does nothing. The optional argument @var{buffer-or-name} may be a | |
1607 | buffer or the name of an existing buffer and defaults to the current | |
1608 | buffer. Invoking this command on a minibuffer signals an error. | |
1609 | ||
1610 | The function @code{delete-windows-on} operates by calling | |
1611 | @code{delete-window} for each window showing @var{buffer-or-name}. If a | |
1612 | frame has several windows showing different buffers, then those showing | |
1613 | @var{buffer-or-name} are removed, and the other windows expand to fill | |
1614 | the space. | |
1615 | ||
1616 | If all windows in some frame are showing @var{buffer-or-name} (including | |
1617 | the case where there is only one window), then that frame is deleted | |
1618 | provided there are other frames left. | |
b8d4c8d0 | 1619 | |
aeeedf76 MR |
1620 | The optional argument @var{frame} specifies which frames to operate on. |
1621 | This function does not use it in quite the same way as the other | |
b33b68a3 MR |
1622 | functions which scan all live windows (@pxref{Cyclic Window Ordering}); |
1623 | specifically, the values @code{t} and @code{nil} have the opposite of | |
1624 | their meanings in the other functions. Here are the full details: | |
b8d4c8d0 GM |
1625 | |
1626 | @itemize @bullet | |
b33b68a3 MR |
1627 | @item @code{nil} |
1628 | means operate on all frames. | |
1629 | @item @code{t} | |
1630 | means operate on the selected frame. | |
1631 | @item @code{visible} | |
1632 | means operate on all visible frames. | |
1633 | @item @code{0} | |
1634 | means operate on all visible or iconified frames. | |
1635 | @item A frame | |
1636 | means operate on that frame. | |
b8d4c8d0 | 1637 | @end itemize |
b8d4c8d0 GM |
1638 | @end deffn |
1639 | ||
b33b68a3 | 1640 | |
b8d4c8d0 GM |
1641 | @node Selecting Windows |
1642 | @section Selecting Windows | |
1643 | @cindex selecting a window | |
1644 | ||
b8d4c8d0 | 1645 | @defun select-window window &optional norecord |
b33b68a3 MR |
1646 | This function makes @var{window} the selected window, see @ref{Basic |
1647 | Windows}. Unless @var{window} already is the selected window, this also | |
1648 | makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current | |
1649 | buffer. Moreover, the cursor for selected windows will be displayed in | |
1650 | @var{window} after the next redisplay. This function returns | |
1651 | @var{window}. | |
b8d4c8d0 | 1652 | |
0273ca3a MR |
1653 | Normally, @var{window}'s selected buffer is moved to the front of the |
1654 | buffer list (@pxref{The Buffer List}) and @var{window} becomes the most | |
b33b68a3 MR |
1655 | recently selected window. But if the optional argument @var{norecord} |
1656 | is non-@code{nil}, the buffer list remains unchanged and @var{window} | |
1657 | does not become the most recently selected one. | |
b8d4c8d0 GM |
1658 | @end defun |
1659 | ||
b33b68a3 MR |
1660 | @cindex most recently selected windows |
1661 | The sequence of calls to @code{select-window} with a non-@code{nil} | |
1662 | @var{norecord} argument determines an ordering of windows by their | |
1663 | selection time. The function @code{get-lru-window} can be used to | |
1664 | retrieve the least recently selected live window in this ordering, see | |
1665 | @ref{Cyclic Window Ordering}. | |
1666 | ||
b8d4c8d0 GM |
1667 | @defmac save-selected-window forms@dots{} |
1668 | This macro records the selected frame, as well as the selected window | |
1669 | of each frame, executes @var{forms} in sequence, then restores the | |
1670 | earlier selected frame and windows. It also saves and restores the | |
1671 | current buffer. It returns the value of the last form in @var{forms}. | |
1672 | ||
1673 | This macro does not save or restore anything about the sizes, | |
a1401ab1 | 1674 | arrangement or contents of windows; therefore, if @var{forms} change |
0273ca3a MR |
1675 | them, the change persists. If the previously selected window of some |
1676 | frame is no longer live at the time of exit from @var{forms}, that | |
1677 | frame's selected window is left alone. If the previously selected | |
1678 | window is no longer live, then whatever window is selected at the end of | |
1679 | @var{forms} remains selected. The current buffer is restored if and | |
1680 | only if it is still live when exiting @var{forms}. | |
1681 | ||
1682 | This macro changes neither the ordering of recently selected windows nor | |
1683 | the buffer list. | |
b8d4c8d0 GM |
1684 | @end defmac |
1685 | ||
1686 | @defmac with-selected-window window forms@dots{} | |
0273ca3a MR |
1687 | This macro selects @var{window}, executes @var{forms} in sequence, then |
1688 | restores the previously selected window and current buffer. The ordering | |
1689 | of recently selected windows and the buffer list remain unchanged unless | |
1690 | you deliberately change them within @var{forms}, for example, by calling | |
b8766179 | 1691 | @code{select-window} with argument @var{norecord} @code{nil}. |
b8d4c8d0 | 1692 | |
b33b68a3 MR |
1693 | The order of recently selected windows and the buffer list are not |
1694 | changed by this macro. | |
1695 | @end defmac | |
b8d4c8d0 | 1696 | |
b33b68a3 MR |
1697 | @cindex frame selected window |
1698 | @cindex window selected within frame | |
1699 | Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly | |
1700 | one window on any frame is selected within the frame. The significance | |
1701 | of this designation is that selecting the frame also selects this | |
1702 | window. Conversely, selecting a window for Emacs with | |
1703 | @code{select-window} also makes that window selected within its frame. | |
1704 | ||
1705 | @defun frame-selected-window &optional frame | |
1706 | This function returns the window on @var{frame} that is selected within | |
1707 | @var{frame}. The optional argument @var{frame} must denote a live frame | |
1708 | and defaults to the selected one. | |
b8d4c8d0 GM |
1709 | @end defun |
1710 | ||
b33b68a3 MR |
1711 | @defun set-frame-selected-window frame window &optional norecord |
1712 | This function sets the selected window of frame @var{frame} to | |
1713 | @var{window}. The argument @var{frame} must denote a live frame and | |
1714 | defaults to the selected one. If @var{frame} is the selected frame, | |
1715 | this also makes @var{window} the selected window. The argument | |
1716 | @var{window} must denote a live window. This function returns | |
1717 | @var{window}. | |
1718 | ||
1719 | Optional argument @var{norecord} non-@code{nil} means to neither change | |
1720 | the list of most recently selected windows (@pxref{Selecting Windows}) | |
1721 | nor the buffer list (@pxref{The Buffer List}). | |
b8d4c8d0 GM |
1722 | @end defun |
1723 | ||
b8d4c8d0 GM |
1724 | |
1725 | @node Cyclic Window Ordering | |
b8d4c8d0 GM |
1726 | @section Cyclic Ordering of Windows |
1727 | @cindex cyclic ordering of windows | |
1728 | @cindex ordering of windows, cyclic | |
1729 | @cindex window ordering, cyclic | |
1730 | ||
b33b68a3 MR |
1731 | When you use the command @kbd{C-x o} (@code{other-window}) to select |
1732 | some other window, it moves through live windows in a specific order. | |
1733 | For any given configuration of windows, this order never varies. It is | |
1734 | called the @dfn{cyclic ordering of windows}. | |
b8d4c8d0 | 1735 | |
b33b68a3 MR |
1736 | For a particular frame, this ordering is determined by the window |
1737 | tree of that frame, see @ref{Windows and Frames}. More precisely, the | |
1738 | ordering is obtained by a depth-first traversal of the frame's window | |
1739 | tree supplemented, if requested, by the frame's minibuffer window. | |
b8d4c8d0 | 1740 | |
b33b68a3 MR |
1741 | If there's just one live frame, the cyclic ordering is the ordering |
1742 | for that frame. Otherwise, the cyclic ordering is obtained by appending | |
1743 | the orderings for individual frames in order of the list of all live | |
1744 | frames, @ref{Finding All Frames}. In any case, the ordering is made | |
1745 | ``cyclic'' by having the last window precede the first window in the | |
1746 | ordering. | |
b8d4c8d0 | 1747 | |
5854c267 | 1748 | @defun next-window &optional window minibuf all-frames |
b8d4c8d0 GM |
1749 | @cindex minibuffer window, and @code{next-window} |
1750 | This function returns the window following @var{window} in the cyclic | |
b33b68a3 MR |
1751 | ordering of windows. The argument @var{window} must specify a live |
1752 | window and defaults to the selected one. | |
b8d4c8d0 | 1753 | |
b33b68a3 MR |
1754 | The optional argument @var{minibuf} specifies whether minibuffer windows |
1755 | shall be included in the cyclic ordering. Normally, when @var{minibuf} | |
1756 | is @code{nil}, a minibuffer window is included only if it is currently | |
1757 | ``active''; this matches the behavior of @kbd{C-x o}. (Note that a | |
1758 | minibuffer window is active as long as its minibuffer is in use; see | |
1759 | @ref{Minibuffers}). | |
b8d4c8d0 | 1760 | |
b33b68a3 MR |
1761 | If @var{minibuf} is @code{t}, the cyclic ordering includes all |
1762 | minibuffer windows. If @var{minibuf} is neither @code{t} nor | |
1763 | @code{nil}, minibuffer windows are not included even if they are active. | |
b8d4c8d0 | 1764 | |
aeeedf76 MR |
1765 | The optional argument @var{all-frames} specifies which frames to |
1766 | consider. Here are the possible values and their meanings: | |
b8d4c8d0 | 1767 | |
b33b68a3 | 1768 | @itemize @bullet |
b8d4c8d0 | 1769 | @item @code{nil} |
b33b68a3 MR |
1770 | means consider all windows on @var{window}'s frame, plus the minibuffer |
1771 | window used by that frame even if it lies in some other frame. If the | |
b8d4c8d0 GM |
1772 | minibuffer counts (as determined by @var{minibuf}), then all windows on |
1773 | all frames that share that minibuffer count too. | |
1774 | ||
1775 | @item @code{t} | |
b33b68a3 | 1776 | means consider all windows on all existing frames. |
b8d4c8d0 GM |
1777 | |
1778 | @item @code{visible} | |
b33b68a3 MR |
1779 | means consider all windows on all visible frames. (To get useful |
1780 | results, ensure that @var{window} is on a visible frame.) | |
b8d4c8d0 GM |
1781 | |
1782 | @item 0 | |
b33b68a3 | 1783 | means consider all windows on all visible or iconified frames. |
b8d4c8d0 | 1784 | |
b33b68a3 MR |
1785 | @item A frame |
1786 | means consider all windows on that frame. | |
b8d4c8d0 | 1787 | |
b33b68a3 MR |
1788 | @item Anything else |
1789 | means consider the windows on @var{window}'s frame, and no others. | |
1790 | @end itemize | |
b8d4c8d0 GM |
1791 | |
1792 | This example assumes there are two windows, both displaying the | |
1793 | buffer @samp{windows.texi}: | |
1794 | ||
1795 | @example | |
1796 | @group | |
1797 | (selected-window) | |
1798 | @result{} #<window 56 on windows.texi> | |
1799 | @end group | |
1800 | @group | |
1801 | (next-window (selected-window)) | |
1802 | @result{} #<window 52 on windows.texi> | |
1803 | @end group | |
1804 | @group | |
1805 | (next-window (next-window (selected-window))) | |
1806 | @result{} #<window 56 on windows.texi> | |
1807 | @end group | |
1808 | @end example | |
5854c267 | 1809 | @end defun |
b8d4c8d0 | 1810 | |
5854c267 | 1811 | @defun previous-window &optional window minibuf all-frames |
b8d4c8d0 GM |
1812 | This function returns the window preceding @var{window} in the cyclic |
1813 | ordering of windows. The other arguments specify which windows to | |
b33b68a3 | 1814 | consider as in @code{next-window}. |
5854c267 | 1815 | @end defun |
b8d4c8d0 GM |
1816 | |
1817 | @deffn Command other-window count &optional all-frames | |
0273ca3a MR |
1818 | This function selects another window in the cyclic ordering of windows. |
1819 | @var{count} specifies the number of windows to skip in the ordering, | |
1820 | starting with the selected window, before making the selection. If | |
1821 | @var{count} is a positive number, it skips @var{count} windows forwards. | |
1822 | @var{count} negative means skip @minus{}@var{count} windows backwards. | |
1823 | If @var{count} is zero, it does not skip any window, thus re-selecting | |
1824 | the selected window. In an interactive call, @var{count} is the numeric | |
1825 | prefix argument. | |
b8d4c8d0 | 1826 | |
aeeedf76 | 1827 | The optional argument @var{all-frames} has the same meaning as in |
b8d4c8d0 | 1828 | @code{next-window}, but the @var{minibuf} argument of @code{next-window} |
0273ca3a | 1829 | is always effectively @code{nil}. This function returns @code{nil}. |
b33b68a3 MR |
1830 | |
1831 | This function does not select a window that has a non-@code{nil} | |
1832 | @code{no-other-window} window parameter (@pxref{Window Parameters}). | |
b8d4c8d0 GM |
1833 | @end deffn |
1834 | ||
b33b68a3 MR |
1835 | The following function returns a copy of the list of windows in the |
1836 | cyclic odering. | |
1837 | ||
1838 | @defun window-list-1 &optional window &optional minibuf &optional all_frames | |
1839 | This function returns a list of live windows. The optional arguments | |
1840 | @var{minibuf} and @var{all-frames} specify the set of windows to include | |
1841 | in the list. See the description of @code{next-window} for details. | |
1842 | ||
1843 | The optional argument @var{window} specifies the first window to list | |
1844 | and defaults to the selected window. If @var{window} is not on the list | |
1845 | of windows returned, some other window will be listed first but no error | |
1846 | is signalled. | |
1847 | @end defun | |
1848 | ||
1849 | The functions described below use @code{window-list-1} for generating a | |
1850 | copy of the list of all relevant windows. Hence, any change of the | |
1851 | window configuration that occurs while one of these functions is | |
1852 | executed is @emph{not} reflected in the list of windows investigated. | |
1853 | ||
b8d4c8d0 | 1854 | @defun walk-windows proc &optional minibuf all-frames |
b33b68a3 MR |
1855 | This function cycles through live windows. It calls the function |
1856 | @var{proc} once for each window, with the window as its sole argument. | |
1857 | ||
1858 | The optional arguments @var{minibuf} and @var{all-frames} specify the | |
1859 | set of windows to include in the walk, see @code{next-window} above. If | |
1860 | @var{all-frames} specifies a frame, the first window walked is the first | |
1861 | window on that frame as returned by @code{frame-first-window} and not | |
1862 | necessarily the selected window. | |
1863 | ||
1864 | If @var{proc} changes the window configuration by splitting or deleting | |
1865 | windows, that change is not reflected in the set of windows walked. | |
1866 | That set is determined entirely by the set of live windows at the time | |
1867 | this function was invoked. | |
1868 | @end defun | |
1869 | ||
1870 | The following function allows to determine whether a specific window is | |
1871 | the only live window. | |
1872 | ||
1873 | @defun one-window-p &optional no-mini all-frames | |
1874 | This function returns non-@code{nil} if the selected window is the only | |
1875 | window. | |
1876 | ||
1877 | The optional argument @var{no-mini}, if non-@code{nil}, means don't | |
1878 | count the minibuffer even if it is active; otherwise, the minibuffer | |
1879 | window is counted when it is active. The optional argument | |
1880 | @var{all-frames} has the same meaning as for @code{next-window}, see | |
1881 | above. | |
1882 | @end defun | |
1883 | ||
1884 | @cindex finding windows | |
1885 | The following functions choose (but do not select) one of the windows | |
1886 | on the screen, offering various criteria for the choice. | |
1887 | ||
1888 | @cindex least recently used window | |
1889 | @defun get-lru-window &optional all-frames dedicated | |
1890 | This function returns the window least recently ``used'' (that is, | |
1891 | selected). If any full-width windows are present, it only considers | |
1892 | these. The optional argument @var{all-frames} has the same meaning as | |
1893 | in @code{next-window}. | |
1894 | ||
1895 | The selected window is returned if it is the only candidate. A | |
1896 | minibuffer window is never a candidate. A dedicated window | |
1897 | (@pxref{Dedicated Windows}) is never a candidate unless the optional | |
1898 | argument @var{dedicated} is non-@code{nil}. | |
1899 | @end defun | |
1900 | ||
1901 | @cindex largest window | |
1902 | @defun get-largest-window &optional all-frames dedicated | |
1903 | This function returns the window with the largest area (height times | |
1904 | width). A minibuffer window is never a candidate. A dedicated window | |
1905 | (@pxref{Dedicated Windows}) is never a candidate unless the optional | |
1906 | argument @var{dedicated} is non-@code{nil}. | |
b8d4c8d0 | 1907 | |
b33b68a3 MR |
1908 | If there are two candidate windows of the same size, this function |
1909 | prefers the one that comes first in the cyclic ordering of windows, | |
1910 | starting from the selected window. | |
1911 | ||
1912 | The optional argument @var{all-frames} specifies which set of windows to | |
1913 | consider as with @code{next-window}, see above. | |
b8d4c8d0 GM |
1914 | @end defun |
1915 | ||
b33b68a3 MR |
1916 | @cindex window that satisfies a predicate |
1917 | @cindex conditional selection of windows | |
1918 | @defun get-window-with-predicate predicate &optional minibuf all-frames default | |
1919 | This function returns a window satisfying @var{predicate}. It cycles | |
1920 | through all visible windows calling @var{predicate} on each one of them | |
1921 | with that window as its argument. The function returns the first window | |
1922 | for which @var{predicate} returns a non-@code{nil} value; if that never | |
1923 | happens, it returns @var{default} (which defaults to @code{nil}). | |
b8d4c8d0 | 1924 | |
b33b68a3 MR |
1925 | The optional arguments @var{minibuf} and @var{all-frames} specify the |
1926 | set of windows to investigate. See the description of | |
1927 | @code{next-window} for details. | |
b8d4c8d0 GM |
1928 | @end defun |
1929 | ||
1930 | @node Buffers and Windows | |
1931 | @section Buffers and Windows | |
1932 | @cindex examining windows | |
1933 | @cindex windows, controlling precisely | |
1934 | @cindex buffers, controlled in windows | |
1935 | ||
b33b68a3 MR |
1936 | To find out which buffer is displayed in a given window the following |
1937 | function is used. | |
b8d4c8d0 | 1938 | |
b33b68a3 MR |
1939 | @defun window-buffer &optional window |
1940 | This function returns the buffer that @var{window} is displaying. The | |
1941 | argument @var{window} can be any window and defaults to the selected | |
1942 | one. If @var{window} is an internal window, this function returns | |
1943 | @code{nil}. | |
1944 | @end defun | |
aeeedf76 | 1945 | |
b33b68a3 MR |
1946 | The basic, low-level function to associate a window with a buffer is |
1947 | @code{set-window-buffer}. Higher-level functions like | |
0e406a72 CY |
1948 | @code{switch-to-buffer} and @code{display-buffer} try to obey a number |
1949 | of user customizations regulating which windows are supposed to | |
1950 | display which buffers. @xref{Switching Buffers}. When writing an | |
1951 | application, you should avoid using @code{set-window-buffer} unless | |
1952 | you are sure you need it. | |
b8d4c8d0 | 1953 | |
b33b68a3 MR |
1954 | @defun set-window-buffer window buffer-or-name &optional keep-margins |
1955 | This function makes @var{window} display @var{buffer-or-name} and | |
1956 | returns @code{nil}. The argument @var{window} has to denote a live | |
1957 | window and defaults to the selected one. The argument | |
1958 | @var{buffer-or-name} must specify a buffer or the name of an existing | |
1959 | buffer. An error is signalled when @var{window} is @dfn{strongly} | |
1960 | dedicated to its buffer (@pxref{Dedicated Windows}) and does not already | |
1961 | display @var{buffer-or-name}. | |
b8d4c8d0 | 1962 | |
0273ca3a MR |
1963 | Normally, displaying @var{buffer-or-name} in @var{window} resets the |
1964 | window's position, display margins, fringe widths, and scroll bar | |
b33b68a3 MR |
1965 | settings based on the local variables of the specified buffer. However, |
1966 | if the optional argument @var{keep-margins} is non-@code{nil}, display | |
1967 | margins and fringe widths of @var{window} remain unchanged. | |
1968 | @xref{Fringes}. | |
1969 | ||
1970 | This function is the fundamental primitive for changing which buffer is | |
1971 | displayed in a window, and all ways of doing that call this function. | |
1972 | Neither the selected window nor the current buffer are changed by this | |
1973 | function. | |
0273ca3a | 1974 | |
b33b68a3 MR |
1975 | This function runs @code{window-scroll-functions} before running |
1976 | @code{window-configuration-change-hook}, see @ref{Window Hooks}. | |
b8d4c8d0 GM |
1977 | @end defun |
1978 | ||
1979 | @defvar buffer-display-count | |
0273ca3a | 1980 | This buffer-local variable records the number of times a buffer has been |
b8d4c8d0 GM |
1981 | displayed in a window. It is incremented each time |
1982 | @code{set-window-buffer} is called for the buffer. | |
1983 | @end defvar | |
1984 | ||
b33b68a3 MR |
1985 | @defvar buffer-display-time |
1986 | This variable records the time at which a buffer was last made visible | |
1987 | in a window. It is always local in each buffer; each time | |
1988 | @code{set-window-buffer} is called, it sets this variable to | |
1989 | @code{(current-time)} in the specified buffer (@pxref{Time of Day}). | |
1990 | When a buffer is first created, @code{buffer-display-time} starts out | |
1991 | with the value @code{nil}. | |
1992 | @end defvar | |
b8d4c8d0 | 1993 | |
520b29e7 | 1994 | @defun get-buffer-window &optional buffer-or-name all-frames |
b33b68a3 MR |
1995 | This function returns a window displaying @var{buffer-or-name}, or |
1996 | @code{nil} if there is none. If there are several such windows, then | |
1997 | the function returns the first one in the cyclic ordering of windows, | |
1998 | starting from the selected window, @xref{Cyclic Window Ordering}. | |
b8d4c8d0 | 1999 | |
b33b68a3 | 2000 | The argument @var{buffer-or-name} may be a buffer or a buffer name and |
aeeedf76 MR |
2001 | defaults to the current buffer. The optional argument @var{all-frames} |
2002 | specifies which windows to consider: | |
b8d4c8d0 GM |
2003 | |
2004 | @itemize @bullet | |
2005 | @item | |
0273ca3a | 2006 | @code{nil} means consider windows on the selected frame. |
b8d4c8d0 | 2007 | @item |
0273ca3a | 2008 | @code{t} means consider windows on all existing frames. |
b8d4c8d0 | 2009 | @item |
0273ca3a | 2010 | @code{visible} means consider windows on all visible frames. |
b8d4c8d0 | 2011 | @item |
0273ca3a | 2012 | 0 means consider windows on all visible or iconified frames. |
b8d4c8d0 | 2013 | @item |
0273ca3a | 2014 | A frame means consider windows on that frame only. |
b8d4c8d0 | 2015 | @end itemize |
0273ca3a MR |
2016 | |
2017 | Observe that the behavior of @code{get-buffer-window} may differ from | |
2018 | that of @code{next-window} (@pxref{Cyclic Window Ordering}) when | |
2019 | @var{all-frames} equals @code{nil} or any value not listed here. | |
2020 | Perhaps we will change @code{get-buffer-window} in the future to make it | |
2021 | compatible with the other functions. | |
b8d4c8d0 GM |
2022 | @end defun |
2023 | ||
520b29e7 MR |
2024 | @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames |
2025 | This function returns a list of all windows currently displaying | |
aeeedf76 MR |
2026 | @var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer |
2027 | or the name of an existing buffer and defaults to the current buffer. | |
b8d4c8d0 | 2028 | |
0273ca3a | 2029 | The two remaining arguments work like the same-named arguments of |
b33b68a3 MR |
2030 | @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} |
2031 | like the optional arguments of @code{get-buffer-window}. | |
b8d4c8d0 GM |
2032 | @end defun |
2033 | ||
b33b68a3 | 2034 | @deffn Command replace-buffer-in-windows &optional buffer-or-name |
0e406a72 CY |
2035 | This command replaces @var{buffer-or-name} with some other buffer, in |
2036 | all windows displaying it. For each such window, it choose another | |
2037 | buffer using @code{switch-to-prev-buffer} (@pxref{Window History}). | |
b33b68a3 | 2038 | |
d83dc65b MR |
2039 | The argument @var{buffer-or-name} may be a buffer, or the name of an |
2040 | existing buffer; it defaults to the current buffer. | |
b33b68a3 MR |
2041 | |
2042 | If a window displaying @var{buffer-or-name} is dedicated | |
d83dc65b MR |
2043 | (@pxref{Dedicated Windows}) and is not the only window on its frame, |
2044 | that window is deleted. If that window is the only window on its frame | |
2045 | and there are other frames on the frame's terminal, that frame is dealt | |
2046 | with by the function spcecified by @code{frame-auto-hide-function} | |
2047 | (@pxref{Quitting Windows}). Otherwise, the buffer provided by the | |
2048 | function @code{switch-to-prev-buffer} (@pxref{Window History}) is | |
2049 | displayed in the window instead. | |
b33b68a3 MR |
2050 | @end deffn |
2051 | ||
590c056d | 2052 | |
0e406a72 CY |
2053 | @node Switching Buffers |
2054 | @section Switching to a Buffer in a Window | |
b8d4c8d0 GM |
2055 | @cindex switching to a buffer |
2056 | @cindex displaying a buffer | |
2057 | ||
0e406a72 CY |
2058 | This section describes high-level functions for switching to a |
2059 | specified buffer in some window. | |
2060 | ||
2061 | Do @emph{not} use these functions to make a buffer temporarily | |
9ec20d36 CY |
2062 | current just so a Lisp program can access or modify it. They have |
2063 | side-effects, such as changing window histories (@pxref{Window | |
2064 | History}), which will surprise the user if used that way. If you want | |
2065 | to make a buffer current to modify it in Lisp, use | |
0e406a72 | 2066 | @code{with-current-buffer}, @code{save-current-buffer}, or |
9ec20d36 | 2067 | @code{set-buffer}. @xref{Current Buffer}. |
0e406a72 CY |
2068 | |
2069 | @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window | |
2070 | This function displays @var{buffer-or-name} in the selected window, | |
2071 | and makes it the current buffer. (In contrast, @code{set-buffer} | |
2072 | makes the buffer current but does not display it; @pxref{Current | |
2073 | Buffer}). It is often used interactively (as the binding of @kbd{C-x | |
2074 | b}), as well as in Lisp programs. The return value is the buffer | |
2075 | switched to. | |
2076 | ||
2077 | If @var{buffer-or-name} is @code{nil}, it defaults to the buffer | |
2078 | returned by @code{other-buffer} (@pxref{The Buffer List}). If | |
2079 | @var{buffer-or-name} is a string that is not the name of any existing | |
2080 | buffer, this function creates a new buffer with that name; the new | |
2081 | buffer's major mode is determined by the variable @code{major-mode} | |
2082 | (@pxref{Major Modes}). | |
2083 | ||
2084 | Normally the specified buffer is put at the front of the buffer | |
2085 | list---both the global buffer list and the selected frame's buffer | |
2086 | list (@pxref{The Buffer List}). However, this is not done if the | |
2087 | optional argument @var{norecord} is non-@code{nil}. | |
2088 | ||
590c056d MR |
2089 | If this function is unable to display the buffer in the selected |
2090 | window---usually because the selected window is a minibuffer window or | |
2091 | is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then | |
2092 | it normally tries to display the buffer in some other window, in the | |
2093 | manner of @code{pop-to-buffer} (see below). However, if the optional | |
2094 | argument @var{force-same-window} is non-@code{nil}, it signals an error | |
0e406a72 | 2095 | instead. |
b8d4c8d0 GM |
2096 | @end deffn |
2097 | ||
2098 | The next two functions are similar to @code{switch-to-buffer}, except | |
2099 | for the described features. | |
2100 | ||
2101 | @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord | |
0e406a72 CY |
2102 | This function makes the buffer specified by @var{buffer-or-name} |
2103 | current and displays it in some window other than the selected window. | |
2104 | It uses the function @code{pop-to-buffer} internally (see below). | |
b8d4c8d0 | 2105 | |
0e406a72 | 2106 | If the selected window already displays the specified buffer, it |
b8766179 | 2107 | continues to do so, but another window is nonetheless found to display |
0e406a72 | 2108 | it as well. |
b8d4c8d0 | 2109 | |
0e406a72 CY |
2110 | The @var{buffer-or-name} and @var{norecord} arguments have the same |
2111 | meanings as in @code{switch-to-buffer}. | |
b8d4c8d0 GM |
2112 | @end deffn |
2113 | ||
0e406a72 CY |
2114 | @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord |
2115 | This function makes the buffer specified by @var{buffer-or-name} | |
2116 | current and displays it, usually in a new frame. It uses the function | |
2117 | @code{pop-to-buffer} (see below). | |
2118 | ||
2119 | If the specified buffer is already displayed in another window, in any | |
2120 | frame on the current terminal, this switches to that window instead of | |
2121 | creating a new frame. However, the selected window is never used for | |
2122 | this. | |
2123 | ||
2124 | The @var{buffer-or-name} and @var{norecord} arguments have the same | |
2125 | meanings as in @code{switch-to-buffer}. | |
2126 | @end deffn | |
2127 | ||
2128 | The above commands use @code{pop-to-buffer}, which is the function | |
2129 | used by Lisp programs to flexibly display a buffer in some window and | |
2130 | select that window for editing: | |
2131 | ||
2132 | @defun pop-to-buffer buffer-or-name &optional action norecord | |
2133 | This function makes @var{buffer-or-name} the current buffer and | |
2134 | displays it in some window, preferably not the window previously | |
2135 | selected. It then selects the displaying window. If that window is | |
2136 | on a different graphical frame, that frame is given input focus if | |
2137 | possible (@pxref{Input Focus}). The return value is the buffer that | |
2138 | was switched to. | |
2139 | ||
2140 | This function uses @code{display-buffer} to display the buffer, so all | |
2141 | the variables affecting @code{display-buffer} will affect it as well. | |
2142 | @xref{Choosing Window}. | |
2143 | ||
2144 | If @var{buffer-or-name} is @code{nil}, it defaults to the buffer | |
2145 | returned by @code{other-buffer} (@pxref{The Buffer List}). If | |
2146 | @var{buffer-or-name} is a string that is not the name of any existing | |
2147 | buffer, this function creates a new buffer with that name; the new | |
2148 | buffer's major mode is determined by the variable @code{major-mode} | |
2149 | (@pxref{Major Modes}). | |
2150 | ||
2151 | If @var{action} is non-@code{nil}, it should be a display action to | |
2152 | pass to @code{display-buffer} (@pxref{Choosing Window}). | |
2153 | Alternatively, a non-@code{nil}, non-list value means to pop to a | |
2154 | window other than the selected one---even if the buffer is already | |
2155 | displayed in the selected window. | |
2156 | ||
2157 | Like @code{switch-to-buffer}, this function updates the buffer list | |
b8d4c8d0 | 2158 | unless @var{norecord} is non-@code{nil}. |
35a30759 | 2159 | @end defun |
b8d4c8d0 | 2160 | |
0e406a72 CY |
2161 | @node Choosing Window |
2162 | @section Choosing a Window for Display | |
b8d4c8d0 | 2163 | |
0e406a72 CY |
2164 | The command @code{display-buffer} flexibly chooses a window for |
2165 | display, and displays a specified buffer in that window. It can be | |
2166 | called interactively, via the key binding @kbd{C-x 4 o}. It is also | |
2167 | used as a subroutine by many functions and commands, including | |
2168 | @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching | |
2169 | Buffers}). | |
2170 | ||
2171 | @cindex display action | |
9ec20d36 CY |
2172 | @cindex action function, for display-buffer |
2173 | @cindex action alist, for display-buffer | |
0e406a72 CY |
2174 | This command performs several complex steps to find a window to |
2175 | display in. These steps are described by means of @dfn{display | |
2176 | actions}, which have the form @code{(@var{function} . @var{alist})}. | |
2177 | Here, @var{function} is either a function or a list of functions, | |
9ec20d36 CY |
2178 | which we refer to as @dfn{action functions}; @var{alist} is an |
2179 | association list, which we refer to as @dfn{action alists}. | |
2180 | ||
2181 | An action function accepts two arguments: the buffer to display and | |
2182 | an action alist. It attempts to display the buffer in some window, | |
2183 | picking or creating a window according to its own criteria. If | |
2184 | successful, it returns the window; otherwise, it returns @code{nil}. | |
2185 | @xref{Display Action Functions}, for a list of predefined action | |
2186 | functions. | |
0e406a72 CY |
2187 | |
2188 | @code{display-buffer} works by combining display actions from | |
9ec20d36 CY |
2189 | several sources, and calling the action functions in turn, until one |
2190 | of them manages to display the buffer and returns a non-@code{nil} | |
0e406a72 CY |
2191 | value. |
2192 | ||
2193 | @deffn Command display-buffer buffer-or-name &optional action frame | |
2194 | This command makes @var{buffer-or-name} appear in some window, without | |
2195 | selecting the window or making the buffer current. The argument | |
2196 | @var{buffer-or-name} must be a buffer or the name of an existing | |
2197 | buffer. The return value is the window chosen to display the buffer. | |
2198 | ||
2199 | The optional argument @var{action}, if non-@code{nil}, should normally | |
2200 | be a display action (described above). @code{display-buffer} builds a | |
2201 | list of action functions and an action alist, by consolidating display | |
2202 | actions from the following sources (in order): | |
2203 | ||
2204 | @itemize | |
2205 | @item | |
2206 | The variable @code{display-buffer-overriding-action}. | |
520b29e7 | 2207 | |
0e406a72 CY |
2208 | @item |
2209 | The user option @code{display-buffer-alist}. | |
250959e0 | 2210 | |
0e406a72 CY |
2211 | @item |
2212 | The @var{action} argument. | |
b8d4c8d0 | 2213 | |
0e406a72 CY |
2214 | @item |
2215 | The user option @code{display-buffer-base-action}. | |
2216 | ||
2217 | @item | |
9ec20d36 | 2218 | The constant @code{display-buffer-fallback-action}. |
0e406a72 | 2219 | @end itemize |
b8d4c8d0 | 2220 | |
0e406a72 CY |
2221 | @noindent |
2222 | Each action function is called in turn, passing the buffer as the | |
2223 | first argument and the combined action alist as the second argument, | |
2224 | until one of the functions returns non-nil. | |
2225 | ||
2226 | The argument @var{action} can also have a non-@code{nil}, non-list | |
2227 | value. This has the special meaning that the buffer should be | |
2228 | displayed in a window other than the selected one, even if the | |
2229 | selected window is already displaying it. If called interactively | |
2230 | with a prefix argument, @var{action} is @code{t}. | |
2231 | ||
2232 | The optional argument @var{frame}, if non-@code{nil}, specifies which | |
2233 | frames to check when deciding whether the buffer is already displayed. | |
9ec20d36 CY |
2234 | It is equivalent to adding an element @code{(reusable-frames |
2235 | . @var{frame})} to the action alist of @var{action}. @xref{Display | |
2236 | Action Functions}. | |
2237 | @end deffn | |
2238 | ||
2239 | @defvar display-buffer-overriding-action | |
2240 | The value of this variable should be a display action, which is | |
2241 | treated with the highest priority by @code{display-buffer}. The | |
2242 | default value is empty, i.e. @code{(nil . nil)}. | |
2243 | @end defvar | |
2244 | ||
2245 | @defopt display-buffer-alist | |
2246 | The value of this option is an alist mapping regular expressions to | |
2247 | display actions. If the name of the buffer passed to | |
2248 | @code{display-buffer} matches a regular expression in this alist, then | |
2249 | @code{display-buffer} uses the corresponding display action. | |
2250 | @end defopt | |
2251 | ||
2252 | @defopt display-buffer-base-action | |
2253 | The value of this option should be a display action. This option can | |
2254 | be used to define a ``standard'' display action for calls to | |
2255 | @code{display-buffer}. | |
2256 | @end defopt | |
2257 | ||
2258 | @defvr Constant display-buffer-fallback-action | |
2259 | This display action specifies the fallback behavior for | |
2260 | @code{display-buffer} if no other display actions are given. | |
2261 | @end defvr | |
2262 | ||
2263 | @node Display Action Functions | |
2264 | @section Action Functions for @code{display-buffer} | |
2265 | ||
2266 | The following basic action functions are defined in Emacs. Each of | |
2267 | these functions takes two arguments: @var{buffer}, the buffer to | |
2268 | display, and @var{alist}, an action alist. Each action function | |
2269 | returns the window if it succeeds, and @code{nil} if it fails. | |
2270 | ||
2271 | @defun display-buffer-same-window buffer alist | |
2272 | This function tries to display @var{buffer} in the selected window. | |
2273 | It fails if the selected window is a minibuffer window or is dedicated | |
2274 | to another buffer (@pxref{Dedicated Windows}). It also fails if | |
2275 | @var{alist} has a non-nil @code{inhibit-same-window} entry. | |
2276 | @end defun | |
2277 | ||
2278 | @defun display-buffer-reuse-window buffer alist | |
2279 | This function tries to ``display'' @var{buffer} by finding a window | |
2280 | that is already displaying it. | |
2281 | ||
2282 | If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, | |
2283 | the selected window is not eligible for reuse. | |
2284 | ||
2285 | If @var{alist} contains a @code{reusable-frames} entry, its value | |
2286 | determines which frames to search for a reusable window: | |
b8d4c8d0 GM |
2287 | |
2288 | @itemize @bullet | |
2289 | @item | |
0273ca3a | 2290 | @code{nil} means consider windows on the selected frame. |
b8d4c8d0 GM |
2291 | (Actually, the last non-minibuffer frame.) |
2292 | @item | |
0273ca3a | 2293 | @code{t} means consider windows on all frames. |
b8d4c8d0 | 2294 | @item |
0273ca3a | 2295 | @code{visible} means consider windows on all visible frames. |
b8d4c8d0 | 2296 | @item |
0273ca3a | 2297 | 0 means consider windows on all visible or iconified frames. |
b8d4c8d0 | 2298 | @item |
0273ca3a | 2299 | A frame means consider windows on that frame only. |
b8d4c8d0 GM |
2300 | @end itemize |
2301 | ||
9ec20d36 CY |
2302 | If @var{alist} contains no @code{reusable-frames} entry, this function |
2303 | normally searches just the selected frame; however, if either the | |
2304 | variable @code{display-buffer-reuse-frames} or the variable | |
2305 | @code{pop-up-frames} is non-@code{nil}, it searches all frames on the | |
2306 | current terminal. @xref{Choosing Window Options}. | |
2307 | @end defun | |
2308 | ||
2309 | @defun display-buffer-pop-up-frame buffer alist | |
2310 | This function creates a new frame, and displays the buffer in that | |
2311 | frame's window. | |
2312 | @end defun | |
2313 | ||
2314 | @defun display-buffer-pop-up-window buffer alist | |
717a1362 CY |
2315 | This function tries to display @var{buffer} by splitting the largest |
2316 | or least recently-used window. It uses @code{split-window-sensibly} | |
2317 | as a subroutine (@pxref{Choosing Window Options}). | |
9ec20d36 CY |
2318 | @end defun |
2319 | ||
2320 | @defun display-buffer-use-some-window buffer alist | |
2321 | This function tries to display @var{buffer} by choosing an existing | |
590c056d | 2322 | window and displaying the buffer in that window. It can fail if all |
9ec20d36 CY |
2323 | windows are dedicated to another buffer (@pxref{Dedicated Windows}). |
2324 | @end defun | |
2325 | ||
2326 | @node Choosing Window Options | |
2327 | @section Additional Options for Displaying Buffers | |
2328 | ||
2329 | The behavior of the standard display actions of @code{display-buffer} | |
2330 | (@pxref{Choosing Window}) can be modified by a variety of user | |
2331 | options. | |
b8d4c8d0 | 2332 | |
52a94b85 MR |
2333 | @defopt display-buffer-reuse-frames |
2334 | If this variable is non-@code{nil}, @code{display-buffer} searches | |
b8766179 MR |
2335 | visible and iconified frames for a window displaying |
2336 | @var{buffer-or-name}. If there is such a window, @code{display-buffer} | |
2337 | makes that window's frame visible and raises it if necessary, and | |
2338 | returns the window. If there is no such window or | |
52a94b85 MR |
2339 | @code{display-buffer-reuse-frames} is @code{nil}, the behavior of |
2340 | @code{display-buffer} is determined by the variables described next. | |
2341 | @end defopt | |
2342 | ||
2343 | @defopt pop-up-windows | |
2344 | This variable specifies whether @code{display-buffer} is allowed to | |
d3c0c321 MR |
2345 | split (@pxref{Splitting Windows}) an existing window. If this variable |
2346 | is non-@code{nil}, @code{display-buffer} tries to split the largest or | |
2347 | least recently used window on the selected frame. (If the selected | |
2348 | frame is a minibuffer-only frame, @code{display-buffer} tries to split a | |
2349 | window on another frame instead.) If this variable is @code{nil} or the | |
b6474f84 | 2350 | variable @code{pop-up-frames} (see below) is non-@code{nil}, |
52a94b85 MR |
2351 | @code{display-buffer} does not split any window. |
2352 | @end defopt | |
2353 | ||
01f17ae2 | 2354 | @defopt split-window-preferred-function |
d3c0c321 MR |
2355 | This variable must specify a function with one argument, which is a |
2356 | window. The @code{display-buffer} routines will call this function with | |
2357 | one or more candidate windows when they look for a window to split. The | |
2358 | function is expected to split that window and return the new window. If | |
2359 | the function returns @code{nil}, this means that the argument window | |
2360 | cannot (or shall not) be split. | |
2361 | ||
2362 | The default value of @code{split-window-preferred-function} is the | |
714c3541 | 2363 | function @code{split-window-sensibly} described below. If you |
d3c0c321 MR |
2364 | customize this option, bear in mind that the @code{display-buffer} |
2365 | routines may call your function up to two times when trying to split a | |
2366 | window. The argument of the first call is the largest window on the | |
2367 | chosen frame (as returned by @code{get-largest-window}). If that call | |
2368 | fails to return a live window, your function is called a second time | |
2369 | with the least recently used window on that frame (as returned by | |
2370 | @code{get-lru-window}). | |
2371 | ||
714c3541 MR |
2372 | The function specified by this option may try to split any other window |
2373 | instead of the argument window. Note that the window selected at the | |
2374 | time @code{display-buffer} was invoked is still selected when your | |
d3c0c321 MR |
2375 | function is called. Hence, you can split the selected window (instead |
2376 | of the largest or least recently used one) by simply ignoring the window | |
2377 | argument in the body of your function. You can even choose to not split | |
2378 | any window as long as the return value of your function specifies a live | |
714c3541 MR |
2379 | window or @code{nil}, but you are not encouraged to do so |
2380 | unconditionally. If you want @code{display-buffer} to never split any | |
2381 | windows, set @code{pop-up-windows} to @code{nil}. | |
01f17ae2 | 2382 | @end defopt |
43c59a3d | 2383 | |
714c3541 | 2384 | @defun split-window-sensibly window |
d3c0c321 MR |
2385 | This function takes a window as argument and tries to split that window |
2386 | in a suitable way. The two variables described next are useful for | |
2387 | tuning the behavior of this function. | |
2388 | @end defun | |
2389 | ||
b8d4c8d0 | 2390 | @defopt split-height-threshold |
372a93ac MR |
2391 | This variable specifies whether @code{split-window-sensibly} may split |
2392 | windows vertically. If it is an integer, @code{split-window-sensibly} | |
2393 | tries to vertically split a window only if it has at least this many | |
2394 | lines. If the window has less lines, splitting fails, or the value of | |
2395 | this variable is @code{nil}, @code{split-window-sensibly} will try to | |
2396 | split the window horizontally, subject to restrictions of | |
714c3541 MR |
2397 | @code{split-width-threshold} (see below). If splitting horizontally |
2398 | fails too and the window is the only window on its frame, | |
2399 | @code{split-window-sensibly} will try to split the window vertically | |
2400 | disregarding the value of @code{split-height-threshold}. If this fails | |
2401 | as well, @code{split-window-sensibly} returns @code{nil}. | |
2402 | ||
2403 | @code{split-window-sensibly} does not split vertically a window whose | |
2404 | height is fixed (@pxref{Resizing Windows}). Also, it vertically splits | |
2405 | a window only if the space taken up by that window can accommodate two | |
2406 | windows one above the other that are both at least | |
2407 | @code{window-min-height} lines tall. Moreover, if the window that shall | |
2408 | be split has a mode line, @code{split-window-sensibly} does not split | |
7ee6a1d3 | 2409 | the window unless the new window can accommodate a mode line too. |
43c59a3d EZ |
2410 | @end defopt |
2411 | ||
2412 | @defopt split-width-threshold | |
372a93ac MR |
2413 | This variable specifies whether @code{split-window-sensibly} may split |
2414 | windows horizontally. If it is an integer, @code{split-window-sensibly} | |
2415 | tries to horizontally split a window only if it has at least this many | |
2416 | columns. If it is @code{nil}, @code{split-window-sensibly} will not | |
2417 | split the window horizontally. (It still might split the window | |
714c3541 MR |
2418 | vertically, though, see above.) |
2419 | ||
2420 | @code{split-window-sensibly} does not split horizontally a window if | |
d3c0c321 | 2421 | that window's width is fixed (@pxref{Resizing Windows}). Also, it |
714c3541 | 2422 | horizontally splits a window only if the space that window takes up can |
d3c0c321 MR |
2423 | accommodate two windows side by side that are both at least |
2424 | @code{window-min-width} columns wide. | |
b8d4c8d0 GM |
2425 | @end defopt |
2426 | ||
2427 | @defopt even-window-heights | |
403b14d1 | 2428 | This variable specifies whether @code{display-buffer} should even out |
52a94b85 MR |
2429 | window heights if the buffer gets displayed in an existing window, above |
2430 | or beneath another window. If @code{even-window-heights} is | |
2431 | non-@code{nil}, the default, window heights will be evened out. If | |
2432 | either of the involved window has fixed height (@pxref{Resizing | |
2433 | Windows}) or @code{even-window-heights} is @code{nil}, the original | |
2434 | window heights will be left alone. | |
b8d4c8d0 GM |
2435 | @end defopt |
2436 | ||
2437 | @c Emacs 19 feature | |
2438 | @defopt pop-up-frames | |
b8766179 MR |
2439 | This variable specifies whether @code{display-buffer} should make new |
2440 | frames. If it is non-@code{nil}, @code{display-buffer} looks for a | |
2441 | window already displaying @var{buffer-or-name} on any visible or | |
2442 | iconified frame. If it finds such a window, it makes that window's | |
2443 | frame visible and raises it if necessary, and returns the window. | |
2444 | Otherwise it makes a new frame, unless the variable's value is | |
2445 | @code{graphic-only} and the selected frame is not on a graphic display. | |
2446 | @xref{Frames}, for more information. | |
b8d4c8d0 | 2447 | |
0273ca3a MR |
2448 | Note that the value of @code{pop-up-windows} does not matter if |
2449 | @code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is | |
2450 | @code{nil}, then @code{display-buffer} either splits a window or reuses | |
2451 | one. | |
b8d4c8d0 GM |
2452 | @end defopt |
2453 | ||
2454 | @c Emacs 19 feature | |
2455 | @defopt pop-up-frame-function | |
2456 | This variable specifies how to make a new frame if @code{pop-up-frames} | |
2457 | is non-@code{nil}. | |
2458 | ||
b8766179 | 2459 | The value of this variable must be a function of no arguments. When |
b8d4c8d0 | 2460 | @code{display-buffer} makes a new frame, it does so by calling that |
b8766179 MR |
2461 | function, which should return a frame. The default value of this |
2462 | variable is a function that creates a frame using the parameters | |
2463 | specified by @code{pop-up-frame-alist} described next. | |
b8d4c8d0 GM |
2464 | @end defopt |
2465 | ||
2466 | @defopt pop-up-frame-alist | |
9f822178 MR |
2467 | This variable holds an alist specifying frame parameters used by the |
2468 | default value of @code{pop-up-frame-function} for making new frames. | |
2469 | @xref{Frame Parameters}, for more information about frame parameters. | |
b8d4c8d0 GM |
2470 | @end defopt |
2471 | ||
2472 | @defopt special-display-buffer-names | |
0273ca3a MR |
2473 | A list of buffer names identifying buffers that should be displayed |
2474 | specially. If the name of @var{buffer-or-name} is in this list, | |
2475 | @code{display-buffer} handles the buffer specially. By default, special | |
2476 | display means to give the buffer a dedicated frame. | |
b8d4c8d0 | 2477 | |
52a94b85 MR |
2478 | If an element is a list, instead of a string, then the @sc{car} of that |
2479 | list is the buffer name, and the rest of that list says how to create | |
2480 | the frame. There are two possibilities for the rest of that list (its | |
2481 | @sc{cdr}): It can be an alist, specifying frame parameters, or it can | |
b8d4c8d0 GM |
2482 | contain a function and arguments to give to it. (The function's first |
2483 | argument is always the buffer to be displayed; the arguments from the | |
2484 | list come after that.) | |
2485 | ||
2486 | For example: | |
2487 | ||
2488 | @example | |
2489 | (("myfile" (minibuffer) (menu-bar-lines . 0))) | |
2490 | @end example | |
2491 | ||
2492 | @noindent | |
2493 | specifies to display a buffer named @samp{myfile} in a dedicated frame | |
2494 | with specified @code{minibuffer} and @code{menu-bar-lines} parameters. | |
2495 | ||
2496 | The list of frame parameters can also use the phony frame parameters | |
2497 | @code{same-frame} and @code{same-window}. If the specified frame | |
2498 | parameters include @code{(same-window . @var{value})} and @var{value} | |
2499 | is non-@code{nil}, that means to display the buffer in the current | |
2500 | selected window. Otherwise, if they include @code{(same-frame . | |
2501 | @var{value})} and @var{value} is non-@code{nil}, that means to display | |
2502 | the buffer in a new window in the currently selected frame. | |
2503 | @end defopt | |
2504 | ||
2505 | @defopt special-display-regexps | |
0273ca3a | 2506 | A list of regular expressions specifying buffers that should be |
b8d4c8d0 GM |
2507 | displayed specially. If the buffer's name matches any of the regular |
2508 | expressions in this list, @code{display-buffer} handles the buffer | |
0273ca3a MR |
2509 | specially. By default, special display means to give the buffer a |
2510 | dedicated frame. | |
b8d4c8d0 GM |
2511 | |
2512 | If an element is a list, instead of a string, then the @sc{car} of the | |
2513 | list is the regular expression, and the rest of the list says how to | |
0273ca3a | 2514 | create the frame. See @code{special-display-buffer-names} above. |
b8d4c8d0 GM |
2515 | @end defopt |
2516 | ||
2517 | @defun special-display-p buffer-name | |
2518 | This function returns non-@code{nil} if displaying a buffer | |
2519 | named @var{buffer-name} with @code{display-buffer} would | |
2520 | create a special frame. The value is @code{t} if it would | |
2521 | use the default frame parameters, or else the specified list | |
2522 | of frame parameters. | |
2523 | @end defun | |
2524 | ||
01f17ae2 | 2525 | @defopt special-display-function |
b8d4c8d0 GM |
2526 | This variable holds the function to call to display a buffer specially. |
2527 | It receives the buffer as an argument, and should return the window in | |
0273ca3a MR |
2528 | which it is displayed. The default value of this variable is |
2529 | @code{special-display-popup-frame}, see below. | |
01f17ae2 | 2530 | @end defopt |
b8d4c8d0 GM |
2531 | |
2532 | @defun special-display-popup-frame buffer &optional args | |
0273ca3a MR |
2533 | This function tries to make @var{buffer} visible in a frame of its own. |
2534 | If @var{buffer} is already displayed in some window, it makes that | |
2535 | window's frame visible and raises it. Otherwise, it creates a frame | |
2536 | that is dedicated to @var{buffer}. The return value is the window used | |
2537 | to display @var{buffer}. | |
b8d4c8d0 GM |
2538 | |
2539 | If @var{args} is an alist, it specifies frame parameters for the new | |
0273ca3a MR |
2540 | frame. If @var{args} is a list whose @sc{car} is a symbol, then |
2541 | @code{(car @var{args})} is called as a function to actually create and | |
2542 | set up the frame; it is called with @var{buffer} as first argument, and | |
2543 | @code{(cdr @var{args})} as additional arguments. | |
b8d4c8d0 GM |
2544 | |
2545 | This function always uses an existing window displaying @var{buffer}, | |
2546 | whether or not it is in a frame of its own; but if you set up the above | |
2547 | variables in your init file, before @var{buffer} was created, then | |
2548 | presumably the window was previously made by this function. | |
2549 | @end defun | |
2550 | ||
2551 | @defopt special-display-frame-alist | |
2552 | @anchor{Definition of special-display-frame-alist} | |
2553 | This variable holds frame parameters for | |
2554 | @code{special-display-popup-frame} to use when it creates a frame. | |
2555 | @end defopt | |
2556 | ||
2557 | @defopt same-window-buffer-names | |
2558 | A list of buffer names for buffers that should be displayed in the | |
2559 | selected window. If the buffer's name is in this list, | |
2560 | @code{display-buffer} handles the buffer by switching to it in the | |
2561 | selected window. | |
2562 | @end defopt | |
2563 | ||
2564 | @defopt same-window-regexps | |
2565 | A list of regular expressions that specify buffers that should be | |
2566 | displayed in the selected window. If the buffer's name matches any of | |
2567 | the regular expressions in this list, @code{display-buffer} handles the | |
2568 | buffer by switching to it in the selected window. | |
2569 | @end defopt | |
2570 | ||
2571 | @defun same-window-p buffer-name | |
2572 | This function returns @code{t} if displaying a buffer | |
2573 | named @var{buffer-name} with @code{display-buffer} would | |
2574 | put it in the selected window. | |
2575 | @end defun | |
2576 | ||
2577 | @c Emacs 19 feature | |
01f17ae2 | 2578 | @defopt display-buffer-function |
b8d4c8d0 GM |
2579 | This variable is the most flexible way to customize the behavior of |
2580 | @code{display-buffer}. If it is non-@code{nil}, it should be a function | |
2581 | that @code{display-buffer} calls to do the work. The function should | |
2582 | accept two arguments, the first two arguments that @code{display-buffer} | |
2583 | received. It should choose or create a window, display the specified | |
2584 | buffer in it, and then return the window. | |
2585 | ||
52a94b85 MR |
2586 | This variable takes precedence over all the other options described |
2587 | above. | |
01f17ae2 | 2588 | @end defopt |
b8d4c8d0 | 2589 | |
52a94b85 | 2590 | If all options described above fail to produce a suitable window, |
0273ca3a MR |
2591 | @code{display-buffer} tries to reuse an existing window. As a last |
2592 | resort, it will try to display @var{buffer-or-name} on a separate frame. | |
2593 | In that case, the value of @code{pop-up-frames} is disregarded. | |
2594 | ||
590c056d | 2595 | |
0e406a72 CY |
2596 | @node Window History |
2597 | @section Window History | |
2598 | @cindex window history | |
2599 | ||
590c056d MR |
2600 | Each window remembers the buffers it has displayed earlier and the order |
2601 | in which these buffers have been removed from it. This history is used, | |
2602 | for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and | |
2603 | Windows}). This list is automatically maintained by Emacs, but you can | |
2604 | use the following functions to explicitly inspect or alter it: | |
0e406a72 CY |
2605 | |
2606 | @defun window-prev-buffers &optional window | |
2607 | This function returns a list specifying the previous contents of | |
2608 | @var{window}, which should be a live window and defaults to the | |
2609 | selected window. | |
2610 | ||
2611 | Each list element has the form @code{(@var{buffer} @var{window-start} | |
2612 | @var{window-pos})}, where @var{buffer} is a buffer previously shown in | |
2613 | the window, @var{window-start} is the window start position when that | |
2614 | buffer was last shown, and @var{window-pos} is the point position when | |
2615 | that buffer was last shown. | |
2616 | ||
2617 | The list is ordered so that earlier elements correspond to more | |
590c056d | 2618 | recently-shown buffers, and the first element usually corresponds to the |
0e406a72 CY |
2619 | buffer most recently removed from the window. |
2620 | @end defun | |
2621 | ||
2622 | @defun set-window-prev-buffers window prev-buffers | |
2623 | This function sets @var{window}'s previous buffers to the value of | |
2624 | @var{prev-buffers}. The argument @var{window} must be a live window | |
2625 | and defaults to the selected one. The argument @var{prev-buffers} | |
2626 | should be a list of the same form as that returned by | |
2627 | @code{window-prev-buffers}. | |
2628 | @end defun | |
2629 | ||
2630 | In addition, each buffer maintains a list of @dfn{next buffers}, which | |
2631 | is a list of buffers re-shown by @code{switch-to-prev-buffer} (see | |
2632 | below). This list is mainly used by @code{switch-to-prev-buffer} and | |
2633 | @code{switch-to-next-buffer} for choosing buffers to switch to. | |
2634 | ||
2635 | @defun window-next-buffers &optional window | |
2636 | This function returns the list of buffers recently re-shown in | |
590c056d MR |
2637 | @var{window} via @code{switch-to-prev-buffer}. The @var{window} |
2638 | argument must denote a live window or @code{nil} (meaning the selected | |
2639 | window). | |
0e406a72 CY |
2640 | @end defun |
2641 | ||
2642 | @defun set-window-next-buffers window next-buffers | |
2643 | This function sets the next buffer list of @var{window} to | |
2644 | @var{next-buffers}. The @var{window} argument should be a live window | |
2645 | or @code{nil} (meaning the selected window). The argument | |
2646 | @var{next-buffers} should be a list of buffers. | |
2647 | @end defun | |
2648 | ||
2649 | The following commands can be used to cycle through the global buffer | |
2650 | list, much like @code{bury-buffer} and @code{unbury-buffer}. However, | |
2651 | they cycle according to the specified window's history list, rather | |
2652 | than the global buffer list. In addition, they restore | |
2653 | window-specific window start and point positions, and may show a | |
2654 | buffer even if it is already shown in another window. The | |
2655 | @code{switch-to-prev-buffer} command, in particular, is used by | |
2656 | @code{replace-buffer-in-windows}, @code{bury-buffer} and | |
2657 | @code{quit-window} to find a replacement buffer for a window. | |
2658 | ||
2659 | @deffn Command switch-to-prev-buffer &optional window bury-or-kill | |
2660 | This command displays the previous buffer in @var{window}. The | |
2661 | argument @var{window} should be a live window or @code{nil} (meaning | |
2662 | the selected window). If the optional argument @var{bury-or-kill} is | |
2663 | non-@code{nil}, this means that the buffer currently shown in | |
2664 | @var{window} is about to be buried or killed and consequently shall | |
2665 | not be switched to in future invocations of this command. | |
2666 | ||
2667 | The previous buffer is usually the buffer shown before the buffer | |
2668 | currently shown in @var{window}. However, a buffer that has been buried | |
2669 | or killed or has been already shown by a recent invocation of | |
2670 | @code{switch-to-prev-buffer} does not qualify as previous buffer. | |
2671 | ||
2672 | If repeated invocations of this command have already shown all buffers | |
2673 | previously shown in @var{window}, further invocations will show buffers | |
590c056d MR |
2674 | from the buffer list of the frame @var{window} appears on (@pxref{The |
2675 | Buffer List}). | |
0e406a72 CY |
2676 | @end deffn |
2677 | ||
2678 | @deffn Command switch-to-next-buffer &optional window | |
2679 | This command switches to the next buffer in @var{window} thus undoing | |
2680 | the effect of the last @code{switch-to-prev-buffer} command in | |
2681 | @var{window}. The argument @var{window} must be a live window and | |
2682 | defaults to the selected one. | |
2683 | ||
590c056d MR |
2684 | If there is no recent invocation of a @code{switch-to-prev-buffer} that |
2685 | can be undone, this function tries to show a buffer from the buffer list | |
2686 | of the frame @var{window} appears on (@pxref{The Buffer List}). | |
0e406a72 CY |
2687 | @end deffn |
2688 | ||
590c056d | 2689 | |
0273ca3a MR |
2690 | @node Dedicated Windows |
2691 | @section Dedicated Windows | |
2692 | @cindex dedicated window | |
2693 | ||
2694 | Functions for displaying a buffer can be told to not use specific | |
df006536 | 2695 | windows by marking these windows as @dfn{dedicated} to their buffers. |
0273ca3a MR |
2696 | @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated |
2697 | window for displaying another buffer in it. @code{get-lru-window} and | |
2698 | @code{get-largest-window} (@pxref{Selecting Windows}) do not consider | |
2699 | dedicated windows as candidates when their @var{dedicated} argument is | |
2700 | non-@code{nil}. The behavior of @code{set-window-buffer} | |
2701 | (@pxref{Buffers and Windows}) with respect to dedicated windows is | |
2702 | slightly different, see below. | |
2703 | ||
0e406a72 CY |
2704 | When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to |
2705 | delete a dedicated window and that window is the only window on its | |
2706 | frame, it deletes the window's frame too, provided there are other | |
2707 | frames left. @code{replace-buffer-in-windows} (@pxref{Switching | |
2708 | Buffers}) tries to delete all dedicated windows showing its buffer | |
2709 | argument. When such a window is the only window on its frame, that | |
2710 | frame is deleted, provided there are other frames left. If there are | |
2711 | no more frames left, some other buffer is displayed in the window, and | |
2712 | the window is marked as non-dedicated. | |
0273ca3a MR |
2713 | |
2714 | When you kill a buffer (@pxref{Killing Buffers}) displayed in a | |
2715 | dedicated window, any such window usually gets deleted too, since | |
2716 | @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning | |
2717 | up windows. Burying a buffer (@pxref{The Buffer List}) deletes the | |
b8766179 MR |
2718 | selected window if it is dedicated to that buffer. If, however, that |
2719 | window is the only window on its frame, @code{bury-buffer} displays | |
2720 | another buffer in it and iconifies the frame. | |
250959e0 MR |
2721 | |
2722 | @defun window-dedicated-p &optional window | |
52a94b85 MR |
2723 | This function returns non-@code{nil} if @var{window} is dedicated to its |
2724 | buffer and @code{nil} otherwise. More precisely, the return value is | |
2725 | the value assigned by the last call of @code{set-window-dedicated-p} for | |
2726 | @var{window} or @code{nil} if that function was never called with | |
aeeedf76 MR |
2727 | @var{window} as its argument. The default for @var{window} is the |
2728 | selected window. | |
b8d4c8d0 GM |
2729 | @end defun |
2730 | ||
2731 | @defun set-window-dedicated-p window flag | |
52a94b85 MR |
2732 | This function marks @var{window} as dedicated to its buffer if |
2733 | @var{flag} is non-@code{nil}, and non-dedicated otherwise. | |
52a94b85 | 2734 | |
0273ca3a MR |
2735 | As a special case, if @var{flag} is @code{t}, @var{window} becomes |
2736 | @dfn{strongly} dedicated to its buffer. @code{set-window-buffer} | |
2737 | signals an error when the window it acts upon is strongly dedicated to | |
2738 | its buffer and does not already display the buffer it is asked to | |
b8766179 MR |
2739 | display. Other functions do not treat @code{t} differently from any |
2740 | non-@code{nil} value. | |
0273ca3a | 2741 | @end defun |
52a94b85 | 2742 | |
c419f5cb MR |
2743 | |
2744 | @node Quitting Windows | |
2745 | @section Quitting Windows | |
2746 | ||
2747 | When you want to get rid of a window used for displaying a buffer you | |
d83dc65b MR |
2748 | can call @code{delete-window} or @code{delete-windows-on} |
2749 | (@pxref{Deleting Windows}) to remove that window from its frame. If the | |
2750 | buffer is shown on a separate frame, you might want to call | |
2751 | @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other | |
2752 | hand, a window has been reused for displaying the buffer, you might | |
2753 | prefer showing the buffer previously shown in that window by calling the | |
2754 | function @code{switch-to-prev-buffer} (@pxref{Window History}). | |
2755 | Finally, you might want to either bury (@pxref{The Buffer List}) or kill | |
c419f5cb MR |
2756 | (@pxref{Killing Buffers}) the window's buffer. |
2757 | ||
2758 | The following function uses information on how the window for | |
2759 | displaying the buffer was obtained in the first place thus attempting to | |
2760 | automatize the above decisions for you. | |
2761 | ||
2762 | @deffn Command quit-window &optional kill window | |
2763 | This command quits @var{window} and buries its buffer. The argument | |
2764 | @var{window} must be a live window and defaults to the selected one. | |
2765 | With prefix argument @var{kill} non-@code{nil}, it kills the buffer | |
2766 | instead of burying it. | |
2767 | ||
2768 | Quitting @var{window} means to proceed as follows: If @var{window} was | |
2769 | created specially for displaying its current buffer, delete @var{window} | |
2770 | provided its frame contains at least one other live window. If | |
d83dc65b MR |
2771 | @var{window} is the only window on its frame and there are other frames |
2772 | on the frame's terminal, the value of @var{kill} determines how to | |
2773 | proceed with the window. If @var{kill} is @code{nil}, the fate of the | |
2774 | frame is determined by calling @code{frame-auto-hide-function} (see | |
2775 | below) with that frame as sole argument. If @var{kill} is | |
2776 | non-@code{nil}, the frame is deleted unconditionally. | |
c419f5cb MR |
2777 | |
2778 | If @var{window} was reused for displaying its buffer, this command tries | |
2779 | to display the buffer previously shown in it. It also tries to restore | |
2780 | the window start (@pxref{Window Start and End}) and point (@pxref{Window | |
2781 | Point}) positions of the previously shown buffer. If, in addition, the | |
2782 | current buffer was temporarily resized, this command will also try to | |
2783 | restore the original height of @var{window}. | |
2784 | ||
2785 | The three cases described so far require that the buffer shown in | |
2786 | @var{window} is still the buffer displayed by the last buffer display | |
2787 | function for this window. If another buffer has been shown in the | |
2788 | meantime or the buffer previously shown no longer exists, this command | |
2789 | calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some | |
2790 | other buffer instead. | |
2791 | @end deffn | |
2792 | ||
2793 | The function @code{quit-window} bases its decisions on information | |
2794 | stored in @var{window}'s @code{quit-restore} window parameter | |
2795 | (@pxref{Window Parameters}) and resets that parameter to @code{nil} | |
2796 | after it's done. | |
2797 | ||
d83dc65b MR |
2798 | The following option specifies how to deal with a frame containing just |
2799 | one window that shall be either quit or whose buffer shall be buried. | |
2800 | ||
2801 | @defopt frame-auto-hide-function | |
2802 | The function specified by this option is called to automatically hide | |
2803 | frames. This function is called with one argument - a frame. | |
2804 | ||
2805 | The function specified here is called by @code{bury-buffer} (@pxref{The | |
2806 | Buffer List}) when the selected window is dedicated and shows the buffer | |
2807 | that shall be buried. It is also called by @code{quit-window} (see | |
2808 | above) when the frame of the window that shall be quit has been | |
2809 | specially created for displaying that window's buffer and the buffer | |
2810 | shall be buried. | |
2811 | ||
2812 | The default is to call @code{iconify-frame} (@pxref{Visibility of | |
2813 | Frames}). Alternatively, you may either specify @code{delete-frame} | |
2814 | (@pxref{Deleting Frames}) to remove the frame from its display, | |
2815 | @code{ignore} to leave the frame unchanged, or any other function that | |
2816 | can take a frame as its sole argument. | |
2817 | ||
2818 | Note that the function specified by this option is called if and only if | |
2819 | there's at least one other frame on the terminal of the frame it's | |
2820 | supposed to handle and that frame contains only one live window. | |
2821 | @end defopt | |
2822 | ||
c419f5cb | 2823 | |
b8d4c8d0 GM |
2824 | @node Window Point |
2825 | @section Windows and Point | |
2826 | @cindex window position | |
2827 | @cindex window point | |
2828 | @cindex position in window | |
2829 | @cindex point in window | |
2830 | ||
0273ca3a MR |
2831 | Each window has its own value of point (@pxref{Point}), independent of |
2832 | the value of point in other windows displaying the same buffer. This | |
2833 | makes it useful to have multiple windows showing one buffer. | |
b8d4c8d0 GM |
2834 | |
2835 | @itemize @bullet | |
2836 | @item | |
2837 | The window point is established when a window is first created; it is | |
2838 | initialized from the buffer's point, or from the window point of another | |
2839 | window opened on the buffer if such a window exists. | |
2840 | ||
2841 | @item | |
2842 | Selecting a window sets the value of point in its buffer from the | |
2843 | window's value of point. Conversely, deselecting a window sets the | |
2844 | window's value of point from that of the buffer. Thus, when you switch | |
2845 | between windows that display a given buffer, the point value for the | |
2846 | selected window is in effect in the buffer, while the point values for | |
2847 | the other windows are stored in those windows. | |
2848 | ||
2849 | @item | |
2850 | As long as the selected window displays the current buffer, the window's | |
2851 | point and the buffer's point always move together; they remain equal. | |
2852 | @end itemize | |
2853 | ||
b8d4c8d0 | 2854 | @cindex cursor |
af1a5cd5 | 2855 | As far as the user is concerned, point is where the cursor is, and |
b8d4c8d0 GM |
2856 | when the user switches to another buffer, the cursor jumps to the |
2857 | position of point in that buffer. | |
2858 | ||
2859 | @defun window-point &optional window | |
2860 | This function returns the current position of point in @var{window}. | |
2861 | For a nonselected window, this is the value point would have (in that | |
aeeedf76 MR |
2862 | window's buffer) if that window were selected. The default for |
2863 | @var{window} is the selected window. | |
b8d4c8d0 GM |
2864 | |
2865 | When @var{window} is the selected window and its buffer is also the | |
2866 | current buffer, the value returned is the same as point in that buffer. | |
0273ca3a MR |
2867 | Strictly speaking, it would be more correct to return the ``top-level'' |
2868 | value of point, outside of any @code{save-excursion} forms. But that | |
2869 | value is hard to find. | |
b8d4c8d0 GM |
2870 | @end defun |
2871 | ||
2872 | @defun set-window-point window position | |
2873 | This function positions point in @var{window} at position | |
2874 | @var{position} in @var{window}'s buffer. It returns @var{position}. | |
2875 | ||
2876 | If @var{window} is selected, and its buffer is current, | |
2877 | this simply does @code{goto-char}. | |
2878 | @end defun | |
2879 | ||
86ab855a MR |
2880 | @defvar window-point-insertion-type |
2881 | This variable specifies the marker insertion type (@pxref{Marker | |
2882 | Insertion Types}) of @code{window-point}. The default is @code{nil}, | |
2883 | so @code{window-point} will stay behind text inserted there. | |
2884 | @end defvar | |
2885 | ||
0273ca3a MR |
2886 | @node Window Start and End |
2887 | @section The Window Start and End Positions | |
b8d4c8d0 GM |
2888 | @cindex window start position |
2889 | ||
0273ca3a | 2890 | Each window maintains a marker used to keep track of a buffer position |
b8d4c8d0 GM |
2891 | that specifies where in the buffer display should start. This position |
2892 | is called the @dfn{display-start} position of the window (or just the | |
2893 | @dfn{start}). The character after this position is the one that appears | |
2894 | at the upper left corner of the window. It is usually, but not | |
2895 | inevitably, at the beginning of a text line. | |
2896 | ||
431b78c9 RS |
2897 | After switching windows or buffers, and in some other cases, if the |
2898 | window start is in the middle of a line, Emacs adjusts the window | |
2899 | start to the start of a line. This prevents certain operations from | |
2900 | leaving the window start at a meaningless point within a line. This | |
2901 | feature may interfere with testing some Lisp code by executing it | |
2902 | using the commands of Lisp mode, because they trigger this | |
2903 | readjustment. To test such code, put it into a command and bind the | |
2904 | command to a key. | |
2905 | ||
b8d4c8d0 GM |
2906 | @defun window-start &optional window |
2907 | @cindex window top line | |
2908 | This function returns the display-start position of window | |
2909 | @var{window}. If @var{window} is @code{nil}, the selected window is | |
2910 | used. For example, | |
2911 | ||
2912 | @example | |
2913 | @group | |
2914 | (window-start) | |
2915 | @result{} 7058 | |
2916 | @end group | |
2917 | @end example | |
2918 | ||
2919 | When you create a window, or display a different buffer in it, the | |
2920 | display-start position is set to a display-start position recently used | |
0273ca3a MR |
2921 | for the same buffer, or to @code{point-min} if the buffer doesn't have |
2922 | any. | |
b8d4c8d0 GM |
2923 | |
2924 | Redisplay updates the window-start position (if you have not specified | |
0273ca3a MR |
2925 | it explicitly since the previous redisplay)---to make sure point appears |
2926 | on the screen. Nothing except redisplay automatically changes the | |
2927 | window-start position; if you move point, do not expect the window-start | |
2928 | position to change in response until after the next redisplay. | |
b8d4c8d0 GM |
2929 | |
2930 | For a realistic example of using @code{window-start}, see the | |
2931 | description of @code{count-lines}. @xref{Definition of count-lines}. | |
2932 | @end defun | |
2933 | ||
0273ca3a | 2934 | @cindex window end position |
b8d4c8d0 | 2935 | @defun window-end &optional window update |
0273ca3a | 2936 | This function returns the position where display of its buffer ends in |
aeeedf76 | 2937 | @var{window}. The default for @var{window} is the selected window. |
b8d4c8d0 GM |
2938 | |
2939 | Simply changing the buffer text or moving point does not update the | |
2940 | value that @code{window-end} returns. The value is updated only when | |
2941 | Emacs redisplays and redisplay completes without being preempted. | |
2942 | ||
2943 | If the last redisplay of @var{window} was preempted, and did not finish, | |
2944 | Emacs does not know the position of the end of display in that window. | |
2945 | In that case, this function returns @code{nil}. | |
2946 | ||
2947 | If @var{update} is non-@code{nil}, @code{window-end} always returns an | |
0273ca3a MR |
2948 | up-to-date value for where display ends, based on the current |
2949 | @code{window-start} value. If a previously saved value of that position | |
2950 | is still valid, @code{window-end} returns that value; otherwise it | |
2951 | computes the correct value by scanning the buffer text. | |
b8d4c8d0 GM |
2952 | |
2953 | Even if @var{update} is non-@code{nil}, @code{window-end} does not | |
2954 | attempt to scroll the display if point has moved off the screen, the | |
2955 | way real redisplay would do. It does not alter the | |
2956 | @code{window-start} value. In effect, it reports where the displayed | |
2957 | text will end if scrolling is not required. | |
2958 | @end defun | |
2959 | ||
2960 | @defun set-window-start window position &optional noforce | |
2961 | This function sets the display-start position of @var{window} to | |
2962 | @var{position} in @var{window}'s buffer. It returns @var{position}. | |
2963 | ||
2964 | The display routines insist that the position of point be visible when a | |
2965 | buffer is displayed. Normally, they change the display-start position | |
2966 | (that is, scroll the window) whenever necessary to make point visible. | |
2967 | However, if you specify the start position with this function using | |
2968 | @code{nil} for @var{noforce}, it means you want display to start at | |
2969 | @var{position} even if that would put the location of point off the | |
2970 | screen. If this does place point off screen, the display routines move | |
2971 | point to the left margin on the middle line in the window. | |
2972 | ||
431b78c9 RS |
2973 | For example, if point @w{is 1} and you set the start of the window |
2974 | @w{to 37}, the start of the next line, point will be ``above'' the top | |
2975 | of the window. The display routines will automatically move point if | |
2976 | it is still 1 when redisplay occurs. Here is an example: | |
b8d4c8d0 GM |
2977 | |
2978 | @example | |
2979 | @group | |
2980 | ;; @r{Here is what @samp{foo} looks like before executing} | |
2981 | ;; @r{the @code{set-window-start} expression.} | |
2982 | @end group | |
2983 | ||
2984 | @group | |
2985 | ---------- Buffer: foo ---------- | |
2986 | @point{}This is the contents of buffer foo. | |
2987 | 2 | |
2988 | 3 | |
2989 | 4 | |
2990 | 5 | |
2991 | 6 | |
2992 | ---------- Buffer: foo ---------- | |
2993 | @end group | |
2994 | ||
2995 | @group | |
2996 | (set-window-start | |
2997 | (selected-window) | |
431b78c9 RS |
2998 | (save-excursion |
2999 | (goto-char 1) | |
3000 | (forward-line 1) | |
3001 | (point))) | |
3002 | @result{} 37 | |
b8d4c8d0 GM |
3003 | @end group |
3004 | ||
3005 | @group | |
3006 | ;; @r{Here is what @samp{foo} looks like after executing} | |
3007 | ;; @r{the @code{set-window-start} expression.} | |
3008 | ---------- Buffer: foo ---------- | |
b8d4c8d0 GM |
3009 | 2 |
3010 | 3 | |
3011 | @point{}4 | |
3012 | 5 | |
3013 | 6 | |
3014 | ---------- Buffer: foo ---------- | |
3015 | @end group | |
3016 | @end example | |
3017 | ||
3018 | If @var{noforce} is non-@code{nil}, and @var{position} would place point | |
3019 | off screen at the next redisplay, then redisplay computes a new window-start | |
3020 | position that works well with point, and thus @var{position} is not used. | |
3021 | @end defun | |
3022 | ||
3023 | @defun pos-visible-in-window-p &optional position window partially | |
3024 | This function returns non-@code{nil} if @var{position} is within the | |
3025 | range of text currently visible on the screen in @var{window}. It | |
0273ca3a MR |
3026 | returns @code{nil} if @var{position} is scrolled vertically out of view. |
3027 | Locations that are partially obscured are not considered visible unless | |
3028 | @var{partially} is non-@code{nil}. The argument @var{position} defaults | |
3029 | to the current position of point in @var{window}; @var{window}, to the | |
3030 | selected window. If @var{position} is @code{t}, that means to check the | |
3031 | last visible position in @var{window}. | |
b8d4c8d0 | 3032 | |
049bcbcb CY |
3033 | This function considers only vertical scrolling. If @var{position} is |
3034 | out of view only because @var{window} has been scrolled horizontally, | |
3035 | @code{pos-visible-in-window-p} returns non-@code{nil} anyway. | |
3036 | @xref{Horizontal Scrolling}. | |
b8d4c8d0 GM |
3037 | |
3038 | If @var{position} is visible, @code{pos-visible-in-window-p} returns | |
3039 | @code{t} if @var{partially} is @code{nil}; if @var{partially} is | |
0273ca3a | 3040 | non-@code{nil}, and the character following @var{position} is fully |
b8d4c8d0 GM |
3041 | visible, it returns a list of the form @code{(@var{x} @var{y})}, where |
3042 | @var{x} and @var{y} are the pixel coordinates relative to the top left | |
0273ca3a MR |
3043 | corner of the window; otherwise it returns an extended list of the form |
3044 | @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, | |
3045 | where @var{rtop} and @var{rbot} specify the number of off-window pixels | |
3046 | at the top and bottom of the row at @var{position}, @var{rowh} specifies | |
3047 | the visible height of that row, and @var{vpos} specifies the vertical | |
3048 | position (zero-based row number) of that row. | |
b8d4c8d0 GM |
3049 | |
3050 | Here is an example: | |
3051 | ||
3052 | @example | |
3053 | @group | |
3054 | ;; @r{If point is off the screen now, recenter it now.} | |
3055 | (or (pos-visible-in-window-p | |
3056 | (point) (selected-window)) | |
3057 | (recenter 0)) | |
3058 | @end group | |
3059 | @end example | |
3060 | @end defun | |
3061 | ||
3062 | @defun window-line-height &optional line window | |
aeeedf76 MR |
3063 | This function returns the height of text line @var{line} in |
3064 | @var{window}. If @var{line} is one of @code{header-line} or | |
3065 | @code{mode-line}, @code{window-line-height} returns information about | |
3066 | the corresponding line of the window. Otherwise, @var{line} is a text | |
3067 | line number starting from 0. A negative number counts from the end of | |
3068 | the window. The default for @var{line} is the current line in | |
3069 | @var{window}; the default for @var{window} is the selected window. | |
b8d4c8d0 GM |
3070 | |
3071 | If the display is not up to date, @code{window-line-height} returns | |
3072 | @code{nil}. In that case, @code{pos-visible-in-window-p} may be used | |
3073 | to obtain related information. | |
3074 | ||
3075 | If there is no line corresponding to the specified @var{line}, | |
3076 | @code{window-line-height} returns @code{nil}. Otherwise, it returns | |
3077 | a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, | |
3078 | where @var{height} is the height in pixels of the visible part of the | |
3079 | line, @var{vpos} and @var{ypos} are the vertical position in lines and | |
3080 | pixels of the line relative to the top of the first text line, and | |
3081 | @var{offbot} is the number of off-window pixels at the bottom of the | |
3082 | text line. If there are off-window pixels at the top of the (first) | |
3083 | text line, @var{ypos} is negative. | |
3084 | @end defun | |
3085 | ||
3086 | @node Textual Scrolling | |
3087 | @section Textual Scrolling | |
3088 | @cindex textual scrolling | |
3089 | @cindex scrolling textually | |
3090 | ||
3091 | @dfn{Textual scrolling} means moving the text up or down through a | |
550f41cd CY |
3092 | window. It works by changing the window's display-start location. It |
3093 | may also change the value of @code{window-point} to keep point on the | |
3094 | screen (@pxref{Window Point}). | |
3095 | ||
3096 | The basic textual scrolling functions are @code{scroll-up} (which | |
3097 | scrolls forward) and @code{scroll-down} (which scrolls backward). In | |
3098 | these function names, ``up'' and ``down'' refer to the direction of | |
3099 | motion of the buffer text relative to the window. Imagine that the | |
3100 | text is written on a long roll of paper and that the scrolling | |
3101 | commands move the paper up and down. Thus, if you are looking at the | |
3102 | middle of a buffer and repeatedly call @code{scroll-down}, you will | |
3103 | eventually see the beginning of the buffer. | |
b8d4c8d0 GM |
3104 | |
3105 | Some people have urged that the opposite convention be used: they | |
550f41cd CY |
3106 | imagine the window moving over text that remains in place, so that |
3107 | ``down'' commands take you to the end of the buffer. This convention | |
3108 | is consistent with fact that such a command is bound to a key named | |
3109 | @key{PageDown} on modern keyboards. We have not switched to this | |
3110 | convention as that is likely to break existing Emacs Lisp code. | |
3111 | ||
3112 | Textual scrolling functions (aside from @code{scroll-other-window}) | |
3113 | have unpredictable results if the current buffer is not the one | |
3114 | displayed in the selected window. @xref{Current Buffer}. | |
3115 | ||
3116 | If the window contains a row taller than the height of the window | |
3117 | (for example in the presence of a large image), the scroll functions | |
3118 | will adjust the window's vertical scroll position to scroll the | |
3119 | partially visible row. Lisp callers can disable this feature by | |
3120 | binding the variable @code{auto-window-vscroll} to @code{nil} | |
3121 | (@pxref{Vertical Scrolling}). | |
b8d4c8d0 GM |
3122 | |
3123 | @deffn Command scroll-up &optional count | |
550f41cd CY |
3124 | This function scrolls forward by @var{count} lines in the selected |
3125 | window. | |
b8d4c8d0 | 3126 | |
550f41cd CY |
3127 | If @var{count} is negative, it scrolls backward instead. If |
3128 | @var{count} is @code{nil} (or omitted), the distance scrolled is | |
3129 | @code{next-screen-context-lines} lines less than the height of the | |
3130 | window's text area. | |
b8d4c8d0 | 3131 | |
550f41cd CY |
3132 | If the selected window cannot be scrolled any further, this function |
3133 | signals an error. Otherwise, it returns @code{nil}. | |
b8d4c8d0 GM |
3134 | @end deffn |
3135 | ||
3136 | @deffn Command scroll-down &optional count | |
550f41cd CY |
3137 | This function scrolls backward by @var{count} lines in the selected |
3138 | window. | |
3139 | ||
3140 | If @var{count} is negative, it scrolls forward instead. If | |
3141 | @var{count} is omitted or @code{nil}, the distance scrolled is | |
3142 | @code{next-screen-context-lines} lines less than the height of the | |
3143 | window's text area. | |
b8d4c8d0 | 3144 | |
550f41cd CY |
3145 | If the selected window cannot be scrolled any further, this function |
3146 | signals an error. Otherwise, it returns @code{nil}. | |
3147 | @end deffn | |
3148 | ||
3149 | @deffn Command scroll-up-command &optional count | |
3150 | This behaves like @code{scroll-up}, except that if the selected window | |
3151 | cannot be scrolled any further and the value of the variable | |
3152 | @code{scroll-error-top-bottom} is @code{t}, it tries to move to the | |
3153 | end of the buffer instead. If point is already there, it signals an | |
3154 | error. | |
3155 | @end deffn | |
b8d4c8d0 | 3156 | |
550f41cd CY |
3157 | @deffn Command scroll-down-command &optional count |
3158 | This behaves like @code{scroll-down}, except that if the selected | |
3159 | window cannot be scrolled any further and the value of the variable | |
3160 | @code{scroll-error-top-bottom} is @code{t}, it tries to move to the | |
3161 | beginning of the buffer instead. If point is already there, it | |
3162 | signals an error. | |
b8d4c8d0 GM |
3163 | @end deffn |
3164 | ||
3165 | @deffn Command scroll-other-window &optional count | |
3166 | This function scrolls the text in another window upward @var{count} | |
3167 | lines. Negative values of @var{count}, or @code{nil}, are handled | |
3168 | as in @code{scroll-up}. | |
3169 | ||
3170 | You can specify which buffer to scroll by setting the variable | |
3171 | @code{other-window-scroll-buffer} to a buffer. If that buffer isn't | |
3172 | already displayed, @code{scroll-other-window} displays it in some | |
3173 | window. | |
3174 | ||
3175 | When the selected window is the minibuffer, the next window is normally | |
3176 | the one at the top left corner. You can specify a different window to | |
3177 | scroll, when the minibuffer is selected, by setting the variable | |
3178 | @code{minibuffer-scroll-window}. This variable has no effect when any | |
3179 | other window is selected. When it is non-@code{nil} and the | |
3180 | minibuffer is selected, it takes precedence over | |
3181 | @code{other-window-scroll-buffer}. @xref{Definition of | |
3182 | minibuffer-scroll-window}. | |
3183 | ||
3184 | When the minibuffer is active, it is the next window if the selected | |
3185 | window is the one at the bottom right corner. In this case, | |
3186 | @code{scroll-other-window} attempts to scroll the minibuffer. If the | |
3187 | minibuffer contains just one line, it has nowhere to scroll to, so the | |
3188 | line reappears after the echo area momentarily displays the message | |
3189 | @samp{Beginning of buffer}. | |
3190 | @end deffn | |
3191 | ||
b8d4c8d0 GM |
3192 | @defvar other-window-scroll-buffer |
3193 | If this variable is non-@code{nil}, it tells @code{scroll-other-window} | |
0273ca3a | 3194 | which buffer's window to scroll. |
b8d4c8d0 GM |
3195 | @end defvar |
3196 | ||
3197 | @defopt scroll-margin | |
3198 | This option specifies the size of the scroll margin---a minimum number | |
3199 | of lines between point and the top or bottom of a window. Whenever | |
3200 | point gets within this many lines of the top or bottom of the window, | |
3201 | redisplay scrolls the text automatically (if possible) to move point | |
3202 | out of the margin, closer to the center of the window. | |
3203 | @end defopt | |
3204 | ||
3205 | @defopt scroll-conservatively | |
3206 | This variable controls how scrolling is done automatically when point | |
3207 | moves off the screen (or into the scroll margin). If the value is a | |
3208 | positive integer @var{n}, then redisplay scrolls the text up to | |
3209 | @var{n} lines in either direction, if that will bring point back into | |
0273ca3a | 3210 | proper view. This behavior is called @dfn{conservative scrolling}. |
b8d4c8d0 GM |
3211 | Otherwise, scrolling happens in the usual way, under the control of |
3212 | other variables such as @code{scroll-up-aggressively} and | |
3213 | @code{scroll-down-aggressively}. | |
3214 | ||
3215 | The default value is zero, which means that conservative scrolling | |
3216 | never happens. | |
3217 | @end defopt | |
3218 | ||
3219 | @defopt scroll-down-aggressively | |
3220 | The value of this variable should be either @code{nil} or a fraction | |
3221 | @var{f} between 0 and 1. If it is a fraction, that specifies where on | |
3222 | the screen to put point when scrolling down. More precisely, when a | |
3223 | window scrolls down because point is above the window start, the new | |
3224 | start position is chosen to put point @var{f} part of the window | |
3225 | height from the top. The larger @var{f}, the more aggressive the | |
3226 | scrolling. | |
3227 | ||
3228 | A value of @code{nil} is equivalent to .5, since its effect is to center | |
3229 | point. This variable automatically becomes buffer-local when set in any | |
3230 | fashion. | |
3231 | @end defopt | |
3232 | ||
3233 | @defopt scroll-up-aggressively | |
3234 | Likewise, for scrolling up. The value, @var{f}, specifies how far | |
3235 | point should be placed from the bottom of the window; thus, as with | |
3236 | @code{scroll-up-aggressively}, a larger value scrolls more aggressively. | |
3237 | @end defopt | |
3238 | ||
3239 | @defopt scroll-step | |
da0bbbc4 CY |
3240 | This variable is an older variant of @code{scroll-conservatively}. |
3241 | The difference is that if its value is @var{n}, that permits scrolling | |
b8d4c8d0 GM |
3242 | only by precisely @var{n} lines, not a smaller number. This feature |
3243 | does not work with @code{scroll-margin}. The default value is zero. | |
3244 | @end defopt | |
3245 | ||
550f41cd | 3246 | @cindex @code{scroll-command} property |
b8d4c8d0 | 3247 | @defopt scroll-preserve-screen-position |
550f41cd CY |
3248 | If this option is @code{t}, whenever a scrolling command moves point |
3249 | off-window, Emacs tries to adjust point to keep the cursor at its old | |
3250 | vertical position in the window, rather than the window edge. | |
3251 | ||
3252 | If the value is non-@code{nil} and not @code{t}, Emacs adjusts point | |
3253 | to keep the cursor at the same vertical position, even if the | |
3254 | scrolling command didn't move point off-window. | |
b8d4c8d0 | 3255 | |
550f41cd CY |
3256 | This option affects all scroll commands that have a non-@code{nil} |
3257 | @code{scroll-command} symbol property. | |
b8d4c8d0 GM |
3258 | @end defopt |
3259 | ||
3260 | @defopt next-screen-context-lines | |
3261 | The value of this variable is the number of lines of continuity to | |
3262 | retain when scrolling by full screens. For example, @code{scroll-up} | |
3263 | with an argument of @code{nil} scrolls so that this many lines at the | |
3264 | bottom of the window appear instead at the top. The default value is | |
3265 | @code{2}. | |
3266 | @end defopt | |
3267 | ||
550f41cd CY |
3268 | @defopt scroll-error-top-bottom |
3269 | If this option is @code{nil} (the default), @code{scroll-up-command} | |
3270 | and @code{scroll-down-command} simply signal an error when no more | |
3271 | scrolling is possible. | |
3272 | ||
3273 | If the value is @code{t}, these commands instead move point to the | |
3274 | beginning or end of the buffer (depending on scrolling direction); | |
3275 | only if point is already on that position do they signal an error. | |
3276 | @end defopt | |
3277 | ||
b8d4c8d0 GM |
3278 | @deffn Command recenter &optional count |
3279 | @cindex centering point | |
3280 | This function scrolls the text in the selected window so that point is | |
3281 | displayed at a specified vertical position within the window. It does | |
3282 | not ``move point'' with respect to the text. | |
3283 | ||
3284 | If @var{count} is a nonnegative number, that puts the line containing | |
3285 | point @var{count} lines down from the top of the window. If | |
3286 | @var{count} is a negative number, then it counts upward from the | |
3287 | bottom of the window, so that @minus{}1 stands for the last usable | |
3288 | line in the window. If @var{count} is a non-@code{nil} list, then it | |
3289 | stands for the line in the middle of the window. | |
3290 | ||
3291 | If @var{count} is @code{nil}, @code{recenter} puts the line containing | |
3292 | point in the middle of the window, then clears and redisplays the entire | |
3293 | selected frame. | |
3294 | ||
3295 | When @code{recenter} is called interactively, @var{count} is the raw | |
3296 | prefix argument. Thus, typing @kbd{C-u} as the prefix sets the | |
3297 | @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets | |
3298 | @var{count} to 4, which positions the current line four lines from the | |
3299 | top. | |
3300 | ||
3301 | With an argument of zero, @code{recenter} positions the current line at | |
3302 | the top of the window. This action is so handy that some people make a | |
3303 | separate key binding to do this. For example, | |
3304 | ||
3305 | @example | |
3306 | @group | |
3307 | (defun line-to-top-of-window () | |
3308 | "Scroll current line to top of window. | |
3309 | Replaces three keystroke sequence C-u 0 C-l." | |
3310 | (interactive) | |
3311 | (recenter 0)) | |
3312 | ||
3313 | (global-set-key [kp-multiply] 'line-to-top-of-window) | |
3314 | @end group | |
3315 | @end example | |
3316 | @end deffn | |
3317 | ||
3318 | @node Vertical Scrolling | |
3319 | @section Vertical Fractional Scrolling | |
3320 | @cindex vertical fractional scrolling | |
0273ca3a | 3321 | @cindex vertical scroll position |
b8d4c8d0 | 3322 | |
af1a5cd5 MR |
3323 | @dfn{Vertical fractional scrolling} means shifting text in a window |
3324 | up or down by a specified multiple or fraction of a line. Each window | |
3325 | has a @dfn{vertical scroll position}, which is a number, never less than | |
0273ca3a MR |
3326 | zero. It specifies how far to raise the contents of the window. |
3327 | Raising the window contents generally makes all or part of some lines | |
3328 | disappear off the top, and all or part of some other lines appear at the | |
3329 | bottom. The usual value is zero. | |
b8d4c8d0 | 3330 | |
af1a5cd5 | 3331 | The vertical scroll position is measured in units of the normal line |
b8d4c8d0 GM |
3332 | height, which is the height of the default font. Thus, if the value is |
3333 | .5, that means the window contents are scrolled up half the normal line | |
3334 | height. If it is 3.3, that means the window contents are scrolled up | |
3335 | somewhat over three times the normal line height. | |
3336 | ||
af1a5cd5 | 3337 | What fraction of a line the vertical scrolling covers, or how many |
b8d4c8d0 GM |
3338 | lines, depends on what the lines contain. A value of .5 could scroll a |
3339 | line whose height is very short off the screen, while a value of 3.3 | |
3340 | could scroll just part of the way through a tall line or an image. | |
3341 | ||
3342 | @defun window-vscroll &optional window pixels-p | |
3343 | This function returns the current vertical scroll position of | |
aeeedf76 MR |
3344 | @var{window}. The default for @var{window} is the selected window. |
3345 | If @var{pixels-p} is non-@code{nil}, the return value is measured in | |
0273ca3a | 3346 | pixels, rather than in units of the normal line height. |
b8d4c8d0 GM |
3347 | |
3348 | @example | |
3349 | @group | |
3350 | (window-vscroll) | |
3351 | @result{} 0 | |
3352 | @end group | |
3353 | @end example | |
3354 | @end defun | |
3355 | ||
3356 | @defun set-window-vscroll window lines &optional pixels-p | |
3357 | This function sets @var{window}'s vertical scroll position to | |
0273ca3a MR |
3358 | @var{lines}. If @var{window} is @code{nil}, the selected window is |
3359 | used. The argument @var{lines} should be zero or positive; if not, it | |
3360 | is taken as zero. | |
b8d4c8d0 | 3361 | |
b8d4c8d0 GM |
3362 | |
3363 | The actual vertical scroll position must always correspond | |
3364 | to an integral number of pixels, so the value you specify | |
3365 | is rounded accordingly. | |
3366 | ||
3367 | The return value is the result of this rounding. | |
3368 | ||
3369 | @example | |
3370 | @group | |
3371 | (set-window-vscroll (selected-window) 1.2) | |
3372 | @result{} 1.13 | |
3373 | @end group | |
3374 | @end example | |
3375 | ||
3376 | If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of | |
3377 | pixels. In this case, the return value is @var{lines}. | |
3378 | @end defun | |
3379 | ||
3380 | @defvar auto-window-vscroll | |
3381 | If this variable is non-@code{nil}, the line-move, scroll-up, and | |
0273ca3a | 3382 | scroll-down functions will automatically modify the vertical scroll |
b8766179 | 3383 | position to scroll through display rows that are taller than the height |
0273ca3a | 3384 | of the window, for example in the presence of large images. |
b8d4c8d0 GM |
3385 | @end defvar |
3386 | ||
3387 | @node Horizontal Scrolling | |
3388 | @section Horizontal Scrolling | |
3389 | @cindex horizontal scrolling | |
3390 | ||
3391 | @dfn{Horizontal scrolling} means shifting the image in the window left | |
3392 | or right by a specified multiple of the normal character width. Each | |
3393 | window has a @dfn{horizontal scroll position}, which is a number, never | |
3394 | less than zero. It specifies how far to shift the contents left. | |
3395 | Shifting the window contents left generally makes all or part of some | |
3396 | characters disappear off the left, and all or part of some other | |
3397 | characters appear at the right. The usual value is zero. | |
3398 | ||
3399 | The horizontal scroll position is measured in units of the normal | |
3400 | character width, which is the width of space in the default font. Thus, | |
3401 | if the value is 5, that means the window contents are scrolled left by 5 | |
3402 | times the normal character width. How many characters actually | |
3403 | disappear off to the left depends on their width, and could vary from | |
3404 | line to line. | |
3405 | ||
3406 | Because we read from side to side in the ``inner loop,'' and from top | |
3407 | to bottom in the ``outer loop,'' the effect of horizontal scrolling is | |
3408 | not like that of textual or vertical scrolling. Textual scrolling | |
3409 | involves selection of a portion of text to display, and vertical | |
3410 | scrolling moves the window contents contiguously; but horizontal | |
3411 | scrolling causes part of @emph{each line} to go off screen. | |
3412 | ||
3413 | Usually, no horizontal scrolling is in effect; then the leftmost | |
3414 | column is at the left edge of the window. In this state, scrolling to | |
3415 | the right is meaningless, since there is no data to the left of the edge | |
3416 | to be revealed by it; so this is not allowed. Scrolling to the left is | |
3417 | allowed; it scrolls the first columns of text off the edge of the window | |
3418 | and can reveal additional columns on the right that were truncated | |
3419 | before. Once a window has a nonzero amount of leftward horizontal | |
3420 | scrolling, you can scroll it back to the right, but only so far as to | |
3421 | reduce the net horizontal scroll to zero. There is no limit to how far | |
3422 | left you can scroll, but eventually all the text will disappear off the | |
3423 | left edge. | |
3424 | ||
3425 | @vindex auto-hscroll-mode | |
3426 | If @code{auto-hscroll-mode} is set, redisplay automatically alters | |
3427 | the horizontal scrolling of a window as necessary to ensure that point | |
3428 | is always visible. However, you can still set the horizontal | |
3429 | scrolling value explicitly. The value you specify serves as a lower | |
3430 | bound for automatic scrolling, i.e. automatic scrolling will not | |
3431 | scroll a window to a column less than the specified one. | |
3432 | ||
3433 | @deffn Command scroll-left &optional count set-minimum | |
3434 | This function scrolls the selected window @var{count} columns to the | |
3435 | left (or to the right if @var{count} is negative). The default | |
3436 | for @var{count} is the window width, minus 2. | |
3437 | ||
3438 | The return value is the total amount of leftward horizontal scrolling in | |
3439 | effect after the change---just like the value returned by | |
3440 | @code{window-hscroll} (below). | |
3441 | ||
3442 | Once you scroll a window as far right as it can go, back to its normal | |
3443 | position where the total leftward scrolling is zero, attempts to scroll | |
3444 | any farther right have no effect. | |
3445 | ||
3446 | If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes | |
3447 | the lower bound for automatic scrolling; that is, automatic scrolling | |
3448 | will not scroll a window to a column less than the value returned by | |
3449 | this function. Interactive calls pass non-@code{nil} for | |
3450 | @var{set-minimum}. | |
3451 | @end deffn | |
3452 | ||
3453 | @deffn Command scroll-right &optional count set-minimum | |
3454 | This function scrolls the selected window @var{count} columns to the | |
3455 | right (or to the left if @var{count} is negative). The default | |
3456 | for @var{count} is the window width, minus 2. Aside from the direction | |
3457 | of scrolling, this works just like @code{scroll-left}. | |
3458 | @end deffn | |
3459 | ||
3460 | @defun window-hscroll &optional window | |
3461 | This function returns the total leftward horizontal scrolling of | |
3462 | @var{window}---the number of columns by which the text in @var{window} | |
aeeedf76 MR |
3463 | is scrolled left past the left margin. The default for |
3464 | @var{window} is the selected window. | |
b8d4c8d0 | 3465 | |
0273ca3a MR |
3466 | The return value is never negative. It is zero when no horizontal |
3467 | scrolling has been done in @var{window} (which is usually the case). | |
b8d4c8d0 | 3468 | |
b8d4c8d0 GM |
3469 | |
3470 | @example | |
3471 | @group | |
3472 | (window-hscroll) | |
3473 | @result{} 0 | |
3474 | @end group | |
3475 | @group | |
3476 | (scroll-left 5) | |
3477 | @result{} 5 | |
3478 | @end group | |
3479 | @group | |
3480 | (window-hscroll) | |
3481 | @result{} 5 | |
3482 | @end group | |
3483 | @end example | |
3484 | @end defun | |
3485 | ||
3486 | @defun set-window-hscroll window columns | |
3487 | This function sets horizontal scrolling of @var{window}. The value of | |
3488 | @var{columns} specifies the amount of scrolling, in terms of columns | |
3489 | from the left margin. The argument @var{columns} should be zero or | |
3490 | positive; if not, it is taken as zero. Fractional values of | |
3491 | @var{columns} are not supported at present. | |
3492 | ||
3493 | Note that @code{set-window-hscroll} may appear not to work if you test | |
3494 | it by evaluating a call with @kbd{M-:} in a simple way. What happens | |
3495 | is that the function sets the horizontal scroll value and returns, but | |
3496 | then redisplay adjusts the horizontal scrolling to make point visible, | |
3497 | and this overrides what the function did. You can observe the | |
3498 | function's effect if you call it while point is sufficiently far from | |
3499 | the left margin that it will remain visible. | |
3500 | ||
3501 | The value returned is @var{columns}. | |
3502 | ||
3503 | @example | |
3504 | @group | |
3505 | (set-window-hscroll (selected-window) 10) | |
3506 | @result{} 10 | |
3507 | @end group | |
3508 | @end example | |
3509 | @end defun | |
3510 | ||
af1a5cd5 MR |
3511 | Here is how you can determine whether a given position @var{position} |
3512 | is off the screen due to horizontal scrolling: | |
b8d4c8d0 GM |
3513 | |
3514 | @example | |
3515 | @group | |
3516 | (defun hscroll-on-screen (window position) | |
3517 | (save-excursion | |
3518 | (goto-char position) | |
3519 | (and | |
3520 | (>= (- (current-column) (window-hscroll window)) 0) | |
3521 | (< (- (current-column) (window-hscroll window)) | |
3522 | (window-width window))))) | |
3523 | @end group | |
3524 | @end example | |
3525 | ||
0273ca3a | 3526 | |
b8d4c8d0 GM |
3527 | @node Coordinates and Windows |
3528 | @section Coordinates and Windows | |
3529 | ||
3530 | This section describes how to relate screen coordinates to windows. | |
3531 | ||
3532 | @defun window-at x y &optional frame | |
3533 | This function returns the window containing the specified cursor | |
3534 | position in the frame @var{frame}. The coordinates @var{x} and @var{y} | |
3535 | are measured in characters and count from the top left corner of the | |
3536 | frame. If they are out of range, @code{window-at} returns @code{nil}. | |
3537 | ||
3538 | If you omit @var{frame}, the selected frame is used. | |
3539 | @end defun | |
3540 | ||
3541 | @defun coordinates-in-window-p coordinates window | |
3542 | This function checks whether a particular frame position falls within | |
3543 | the window @var{window}. | |
3544 | ||
3545 | The argument @var{coordinates} is a cons cell of the form @code{(@var{x} | |
3546 | . @var{y})}. The coordinates @var{x} and @var{y} are measured in | |
3547 | characters, and count from the top left corner of the screen or frame. | |
3548 | ||
3549 | The value returned by @code{coordinates-in-window-p} is non-@code{nil} | |
3550 | if the coordinates are inside @var{window}. The value also indicates | |
3551 | what part of the window the position is in, as follows: | |
3552 | ||
3553 | @table @code | |
3554 | @item (@var{relx} . @var{rely}) | |
3555 | The coordinates are inside @var{window}. The numbers @var{relx} and | |
3556 | @var{rely} are the equivalent window-relative coordinates for the | |
3557 | specified position, counting from 0 at the top left corner of the | |
3558 | window. | |
3559 | ||
3560 | @item mode-line | |
3561 | The coordinates are in the mode line of @var{window}. | |
3562 | ||
3563 | @item header-line | |
3564 | The coordinates are in the header line of @var{window}. | |
3565 | ||
3566 | @item vertical-line | |
3567 | The coordinates are in the vertical line between @var{window} and its | |
3568 | neighbor to the right. This value occurs only if the window doesn't | |
3569 | have a scroll bar; positions in a scroll bar are considered outside the | |
3570 | window for these purposes. | |
3571 | ||
3572 | @item left-fringe | |
3573 | @itemx right-fringe | |
3574 | The coordinates are in the left or right fringe of the window. | |
3575 | ||
3576 | @item left-margin | |
3577 | @itemx right-margin | |
3578 | The coordinates are in the left or right margin of the window. | |
3579 | ||
3580 | @item nil | |
3581 | The coordinates are not in any part of @var{window}. | |
3582 | @end table | |
3583 | ||
3584 | The function @code{coordinates-in-window-p} does not require a frame as | |
3585 | argument because it always uses the frame that @var{window} is on. | |
3586 | @end defun | |
3587 | ||
b8d4c8d0 GM |
3588 | |
3589 | @node Window Configurations | |
3590 | @section Window Configurations | |
3591 | @cindex window configurations | |
3592 | @cindex saving window information | |
3593 | ||
c419f5cb | 3594 | A @dfn{window configuration} records the entire layout of one |
0273ca3a MR |
3595 | frame---all windows, their sizes, which buffers they contain, how those |
3596 | buffers are scrolled, and their values of point and the mark; also their | |
3597 | fringes, margins, and scroll bar settings. It also includes the value | |
3598 | of @code{minibuffer-scroll-window}. As a special exception, the window | |
3599 | configuration does not record the value of point in the selected window | |
c419f5cb | 3600 | for the current buffer. |
0273ca3a | 3601 | |
a1401ab1 EZ |
3602 | You can bring back an entire frame layout by restoring a previously |
3603 | saved window configuration. If you want to record the layout of all | |
0273ca3a | 3604 | frames instead of just one, use a frame configuration instead of a |
47264a97 | 3605 | window configuration; see @ref{Frame Configurations}. |
b8d4c8d0 GM |
3606 | |
3607 | @defun current-window-configuration &optional frame | |
3608 | This function returns a new object representing @var{frame}'s current | |
aeeedf76 MR |
3609 | window configuration. The default for @var{frame} is the selected |
3610 | frame. | |
b8d4c8d0 GM |
3611 | @end defun |
3612 | ||
3613 | @defun set-window-configuration configuration | |
3614 | This function restores the configuration of windows and buffers as | |
3615 | specified by @var{configuration}, for the frame that @var{configuration} | |
3616 | was created for. | |
3617 | ||
3618 | The argument @var{configuration} must be a value that was previously | |
0273ca3a | 3619 | returned by @code{current-window-configuration}. The configuration is |
b8d4c8d0 GM |
3620 | restored in the frame from which @var{configuration} was made, whether |
3621 | that frame is selected or not. This always counts as a window size | |
3622 | change and triggers execution of the @code{window-size-change-functions} | |
3623 | (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't | |
3624 | know how to tell whether the new configuration actually differs from the | |
3625 | old one. | |
3626 | ||
3627 | If the frame which @var{configuration} was saved from is dead, all this | |
3628 | function does is restore the three variables @code{window-min-height}, | |
3629 | @code{window-min-width} and @code{minibuffer-scroll-window}. In this | |
3630 | case, the function returns @code{nil}. Otherwise, it returns @code{t}. | |
3631 | ||
3632 | Here is a way of using this function to get the same effect | |
3633 | as @code{save-window-excursion}: | |
3634 | ||
3635 | @example | |
3636 | @group | |
3637 | (let ((config (current-window-configuration))) | |
3638 | (unwind-protect | |
291d142b | 3639 | (progn (split-window-below nil) |
b8d4c8d0 GM |
3640 | @dots{}) |
3641 | (set-window-configuration config))) | |
3642 | @end group | |
3643 | @end example | |
3644 | @end defun | |
3645 | ||
3646 | @defspec save-window-excursion forms@dots{} | |
3647 | This special form records the window configuration, executes @var{forms} | |
3648 | in sequence, then restores the earlier window configuration. The window | |
3649 | configuration includes, for each window, the value of point and the | |
3650 | portion of the buffer that is visible. It also includes the choice of | |
3651 | selected window. However, it does not include the value of point in | |
3652 | the current buffer; use @code{save-excursion} also, if you wish to | |
3653 | preserve that. | |
3654 | ||
3655 | Don't use this construct when @code{save-selected-window} is sufficient. | |
3656 | ||
0273ca3a | 3657 | Exit from @code{save-window-excursion} always triggers execution of |
b8d4c8d0 GM |
3658 | @code{window-size-change-functions}. (It doesn't know how to tell |
3659 | whether the restored configuration actually differs from the one in | |
3660 | effect at the end of the @var{forms}.) | |
3661 | ||
3662 | The return value is the value of the final form in @var{forms}. | |
3663 | For example: | |
3664 | ||
3665 | @example | |
3666 | @group | |
3667 | (split-window) | |
3668 | @result{} #<window 25 on control.texi> | |
3669 | @end group | |
3670 | @group | |
3671 | (setq w (selected-window)) | |
3672 | @result{} #<window 19 on control.texi> | |
3673 | @end group | |
3674 | @group | |
3675 | (save-window-excursion | |
3676 | (delete-other-windows w) | |
3677 | (switch-to-buffer "foo") | |
3678 | 'do-something) | |
3679 | @result{} do-something | |
3680 | ;; @r{The screen is now split again.} | |
3681 | @end group | |
3682 | @end example | |
3683 | @end defspec | |
3684 | ||
3685 | @defun window-configuration-p object | |
3686 | This function returns @code{t} if @var{object} is a window configuration. | |
3687 | @end defun | |
3688 | ||
3689 | @defun compare-window-configurations config1 config2 | |
3690 | This function compares two window configurations as regards the | |
3691 | structure of windows, but ignores the values of point and mark and the | |
3692 | saved scrolling positions---it can return @code{t} even if those | |
3693 | aspects differ. | |
3694 | ||
3695 | The function @code{equal} can also compare two window configurations; it | |
3696 | regards configurations as unequal if they differ in any respect, even a | |
3697 | saved point or mark. | |
3698 | @end defun | |
3699 | ||
3700 | @defun window-configuration-frame config | |
3701 | This function returns the frame for which the window configuration | |
3702 | @var{config} was made. | |
3703 | @end defun | |
3704 | ||
3705 | Other primitives to look inside of window configurations would make | |
3706 | sense, but are not implemented because we did not need them. See the | |
3707 | file @file{winner.el} for some more operations on windows | |
3708 | configurations. | |
3709 | ||
c419f5cb MR |
3710 | The objects returned by @code{current-window-configuration} die |
3711 | together with the Emacs process. In order to store a window | |
3712 | configuration on disk and read it back in another Emacs session the | |
3713 | following two functions can be used. | |
3714 | ||
3715 | @defun window-state-get &optional window markers | |
3716 | This function returns the state of @var{window} as a Lisp object. The | |
3717 | argument @var{window} can be any window and defaults to the root window | |
3718 | of the selected frame. | |
3719 | ||
3720 | The optional argument @var{markers} non-@code{nil} means to use markers | |
3721 | for sampling positions like @code{window-point} or @code{window-start}. | |
3722 | This argument should be non-@code{nil} only if the value is used for | |
3723 | putting the state back in the same session since markers slow down | |
3724 | processing. | |
3725 | @end defun | |
3726 | ||
3727 | The value returned by @code{window-state-get} can be converted by using | |
3728 | one of the functions defined by Desktop Save Mode (@pxref{Desktop Save | |
3729 | Mode}) to an object that can be written to a file. Such objects can be | |
3730 | read back and converted to a Lisp object representing the state of the | |
3731 | window. That Lisp object can be used as argument for the following | |
3732 | function in order to restore the state window in another window. | |
3733 | ||
3734 | @defun window-state-put state &optional window ignore | |
3735 | This function puts the window state @var{state} into @var{window}. The | |
3736 | argument @var{state} should be the state of a window returned by an | |
3737 | earlier invocation of @code{window-state-get}, see above. The optional | |
3738 | argument @var{window} must specify a live window and defaults to the | |
3739 | selected one. | |
3740 | ||
3741 | The optional argument @var{ignore} non-@code{nil} means to ignore | |
3742 | minimum window sizes and fixed size restrictions. If @var{ignore} | |
be7f5545 | 3743 | equals @code{safe}, this means windows can get as small as one line |
c419f5cb MR |
3744 | and/or two columns. |
3745 | @end defun | |
3746 | ||
3747 | ||
0273ca3a MR |
3748 | @node Window Parameters |
3749 | @section Window Parameters | |
3750 | @cindex window parameters | |
3751 | ||
c419f5cb | 3752 | This section describes how window parameters can be used to associate |
0273ca3a MR |
3753 | additional information with windows. |
3754 | ||
3755 | @defun window-parameter window parameter | |
aeeedf76 | 3756 | This function returns @var{window}'s value for @var{parameter}. The |
c419f5cb MR |
3757 | default for @var{window} is the selected window. If @var{window} has no |
3758 | setting for @var{parameter}, this function returns @code{nil}. | |
0273ca3a MR |
3759 | @end defun |
3760 | ||
a1401ab1 | 3761 | @defun window-parameters &optional window |
0273ca3a | 3762 | This function returns all parameters of @var{window} and their values. |
c419f5cb MR |
3763 | The default for @var{window} is the selected window. The return value, |
3764 | if non-@code{nil} is an association list whose elements have the form | |
3765 | @code{(@var{parameter} . @var{value})}. | |
0273ca3a MR |
3766 | @end defun |
3767 | ||
3768 | @defun set-window-parameter window parameter value | |
3769 | This function sets @var{window}'s value of @var{parameter} to | |
aeeedf76 MR |
3770 | @var{value} and returns @var{value}. The default for @var{window} |
3771 | is the selected window. | |
0273ca3a MR |
3772 | @end defun |
3773 | ||
c419f5cb MR |
3774 | Some functions, notably @code{delete-window}, |
3775 | @code{delete-other-windows} and @code{split-window} may behave specially | |
3776 | when their @var{window} argument has a parameter set. You can override | |
3777 | such special behavior by binding the following variable to a | |
3778 | non-@code{nil} value: | |
3779 | ||
3780 | @defvar ignore-window-parameters | |
3781 | If this variable is non-@code{nil}, some standard functions do not | |
3782 | process window parameters. The functions currently affected by this are | |
3783 | @code{split-window}, @code{delete-window}, @code{delete-other-windows} | |
3784 | and @code{other-window}. | |
3785 | ||
3786 | An application can bind this variable to a non-@code{nil} value around | |
3787 | calls to these functions. If it does so, the application is fully | |
3788 | responsible for correctly assigning the parameters of all involved | |
3789 | windows when exiting that function. | |
3790 | @end defvar | |
3791 | ||
3792 | The following parameters are currently used by the window management | |
3793 | code. | |
3794 | ||
3795 | @table @asis | |
3796 | @item @code{delete-window} | |
3797 | This parameter affects the execution of @code{delete-window} | |
3798 | (@pxref{Deleting Windows}). | |
3799 | ||
3800 | @item @code{delete-other-windows} | |
3801 | This parameter affects the execution of @code{delete-other-windows} | |
3802 | (@pxref{Deleting Windows}). | |
3803 | ||
3804 | @item @code{split-window} | |
3805 | This parameter affects the execution of @code{split-window} | |
3806 | (@pxref{Splitting Windows}). | |
3807 | ||
3808 | @item @code{other-window} | |
3809 | This parameter affects the execution of @code{other-window} | |
3810 | (@pxref{Cyclic Window Ordering}). | |
3811 | ||
3812 | @item @code{no-other-window} | |
3813 | This parameter marks the window as not selectable by @code{other-window} | |
3814 | (@pxref{Cyclic Window Ordering}). | |
3815 | @end table | |
3816 | ||
3817 | In addition, the parameters @code{window-atom} and @code{window-side} | |
3818 | are reserved and should not be used by applications. The | |
3819 | @code{quit-restore} parameter tells how to proceed with a window when | |
3820 | the buffer it shows is no more needed. This parameter is installed by | |
3821 | the buffer display functions (@pxref{Choosing Window}) and consulted by | |
3822 | the function @code{quit-window} (@pxref{Quitting Windows}). | |
3823 | ||
0273ca3a | 3824 | |
b8d4c8d0 GM |
3825 | @node Window Hooks |
3826 | @section Hooks for Window Scrolling and Changes | |
3827 | @cindex hooks for window operations | |
3828 | ||
3829 | This section describes how a Lisp program can take action whenever a | |
3830 | window displays a different part of its buffer or a different buffer. | |
3831 | There are three actions that can change this: scrolling the window, | |
3832 | switching buffers in the window, and changing the size of the window. | |
3833 | The first two actions run @code{window-scroll-functions}; the last runs | |
3834 | @code{window-size-change-functions}. | |
3835 | ||
3836 | @defvar window-scroll-functions | |
3837 | This variable holds a list of functions that Emacs should call before | |
0273ca3a MR |
3838 | redisplaying a window with scrolling. Displaying a different buffer in |
3839 | the window also runs these functions. | |
b8d4c8d0 | 3840 | |
0273ca3a MR |
3841 | This variable is not a normal hook, because each function is called with |
3842 | two arguments: the window, and its new display-start position. | |
b8d4c8d0 GM |
3843 | |
3844 | These functions must be careful in using @code{window-end} | |
0273ca3a MR |
3845 | (@pxref{Window Start and End}); if you need an up-to-date value, you |
3846 | must use the @var{update} argument to ensure you get it. | |
b8d4c8d0 GM |
3847 | |
3848 | @strong{Warning:} don't use this feature to alter the way the window | |
3849 | is scrolled. It's not designed for that, and such use probably won't | |
3850 | work. | |
3851 | @end defvar | |
3852 | ||
3853 | @defvar window-size-change-functions | |
3854 | This variable holds a list of functions to be called if the size of any | |
3855 | window changes for any reason. The functions are called just once per | |
3856 | redisplay, and just once for each frame on which size changes have | |
3857 | occurred. | |
3858 | ||
3859 | Each function receives the frame as its sole argument. There is no | |
3860 | direct way to find out which windows on that frame have changed size, or | |
3861 | precisely how. However, if a size-change function records, at each | |
3862 | call, the existing windows and their sizes, it can also compare the | |
3863 | present sizes and the previous sizes. | |
3864 | ||
3865 | Creating or deleting windows counts as a size change, and therefore | |
3866 | causes these functions to be called. Changing the frame size also | |
3867 | counts, because it changes the sizes of the existing windows. | |
3868 | ||
3869 | It is not a good idea to use @code{save-window-excursion} (@pxref{Window | |
3870 | Configurations}) in these functions, because that always counts as a | |
3871 | size change, and it would cause these functions to be called over and | |
3872 | over. In most cases, @code{save-selected-window} (@pxref{Selecting | |
3873 | Windows}) is what you need here. | |
3874 | @end defvar | |
3875 | ||
b8d4c8d0 GM |
3876 | @defvar window-configuration-change-hook |
3877 | A normal hook that is run every time you change the window configuration | |
3878 | of an existing frame. This includes splitting or deleting windows, | |
3879 | changing the sizes of windows, or displaying a different buffer in a | |
0273ca3a MR |
3880 | window. |
3881 | ||
3882 | The buffer-local part of this hook is run once per each window on the | |
3883 | affected frame, with the relevant window selected and its buffer | |
3884 | current. The global part is run once for the modified frame, with that | |
3885 | frame selected. | |
b8d4c8d0 GM |
3886 | @end defvar |
3887 | ||
38b1d346 | 3888 | In addition, you can use @code{jit-lock-register} to register a Font |
b8766179 MR |
3889 | Lock fontification function, which will be called whenever parts of a |
3890 | buffer are (re)fontified because a window was scrolled or its size | |
3891 | changed. @xref{Other Font Lock Variables}. |