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