Mercurial > emacs
comparison lispref/windows.texi @ 25751:467b88fab665
*** empty log message ***
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Fri, 17 Sep 1999 06:59:04 +0000 |
parents | dfac7398266b |
children | fc4fefae9970 |
comparison
equal
deleted
inserted
replaced
25750:f1968a807f56 | 25751:467b88fab665 |
---|---|
21 and choosing a window for it. | 21 and choosing a window for it. |
22 * Choosing Window:: How to choose a window for displaying a buffer. | 22 * Choosing Window:: How to choose a window for displaying a buffer. |
23 * Window Point:: Each window has its own location of point. | 23 * Window Point:: Each window has its own location of point. |
24 * Window Start:: The display-start position controls which text | 24 * Window Start:: The display-start position controls which text |
25 is on-screen in the window. | 25 is on-screen in the window. |
26 * Vertical Scrolling:: Moving text up and down in the window. | 26 * Textual Scrolling:: Moving text up and down through the window. |
27 * Horizontal Scrolling:: Moving text sideways on the window. | 27 * Vertical Scrolling:: Moving the contents up and down on the window. |
28 * Horizontal Scrolling:: Moving the contents sideways on the window. | |
28 * Size of Window:: Accessing the size of a window. | 29 * Size of Window:: Accessing the size of a window. |
29 * Resizing Windows:: Changing the size of a window. | 30 * Resizing Windows:: Changing the size of a window. |
30 * Coordinates and Windows:: Converting coordinates to windows. | 31 * Coordinates and Windows:: Converting coordinates to windows. |
31 * Window Configurations:: Saving and restoring the state of the screen. | 32 * Window Configurations:: Saving and restoring the state of the screen. |
32 * Window Hooks:: Hooks for scrolling, window size changes, | 33 * Window Hooks:: Hooks for scrolling, window size changes, |
249 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|} | 250 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|} |
250 characters. The display table can specify alternative border | 251 characters. The display table can specify alternative border |
251 characters; see @ref{Display Tables}. | 252 characters; see @ref{Display Tables}. |
252 @end deffn | 253 @end deffn |
253 | 254 |
254 @deffn Command split-window-vertically size | 255 @deffn Command split-window-vertically &optional size |
255 This function splits the selected window into two windows, one above the | 256 This function splits the selected window into two windows, one above the |
256 other, leaving the upper of the two windows selected, with @var{size} | 257 other, leaving the upper of the two windows selected, with @var{size} |
257 lines. (If @var{size} is negative, then the lower of the two windows | 258 lines. (If @var{size} is negative, then the lower of the two windows |
258 gets @minus{} @var{size} lines and the upper window gets the rest, but | 259 gets @minus{} @var{size} lines and the upper window gets the rest, but |
259 the upper window is still the one selected.) | 260 the upper window is still the one selected.) |
260 | |
261 This function is simply an interface to @code{split-window}. | |
262 Here is the complete function definition for it: | |
263 | |
264 @smallexample | |
265 @group | |
266 (defun split-window-vertically (&optional arg) | |
267 "Split current window into two windows, @dots{}" | |
268 (interactive "P") | |
269 (split-window nil (and arg (prefix-numeric-value arg)))) | |
270 @end group | |
271 @end smallexample | |
272 @end deffn | 261 @end deffn |
273 | 262 |
274 @deffn Command split-window-horizontally size | 263 @deffn Command split-window-horizontally size |
275 This function splits the selected window into two windows | 264 This function splits the selected window into two windows |
276 side-by-side, leaving the selected window with @var{size} columns. | 265 side-by-side, leaving the selected window with @var{size} columns. |
277 | 266 |
278 This function is simply an interface to @code{split-window}. Here is | 267 This function is basically an interface to @code{split-window}. |
279 the complete definition for @code{split-window-horizontally} (except for | 268 You could define a simplified version of the function like this: |
280 part of the documentation string): | |
281 | 269 |
282 @smallexample | 270 @smallexample |
283 @group | 271 @group |
284 (defun split-window-horizontally (&optional arg) | 272 (defun split-window-horizontally (&optional arg) |
285 "Split selected window into two windows, side by side..." | 273 "Split selected window into two windows, side by side..." |
286 (interactive "P") | 274 (interactive "P") |
287 (split-window nil (and arg (prefix-numeric-value arg)) t)) | 275 @endgroup |
276 @group | |
277 (let ((size (and arg (prefix-numeric-value arg)))) | |
278 (and size (< size 0) | |
279 (setq size (+ (window-width) size))) | |
280 (split-window nil size t))) | |
288 @end group | 281 @end group |
289 @end smallexample | 282 @end smallexample |
290 @end deffn | 283 @end deffn |
291 | 284 |
292 @defun one-window-p &optional no-mini all-frames | 285 @defun one-window-p &optional no-mini all-frames |
563 This function returns the window preceding @var{window} in the cyclic | 556 This function returns the window preceding @var{window} in the cyclic |
564 ordering of windows. The other arguments specify which windows to | 557 ordering of windows. The other arguments specify which windows to |
565 include in the cycle, as in @code{next-window}. | 558 include in the cycle, as in @code{next-window}. |
566 @end defun | 559 @end defun |
567 | 560 |
568 @deffn Command other-window count | 561 @deffn Command other-window count &optional all-frames |
569 This function selects the @var{count}th following window in the cyclic | 562 This function selects the @var{count}th following window in the cyclic |
570 order. If count is negative, then it moves back @minus{}@var{count} | 563 order. If count is negative, then it moves back @minus{}@var{count} |
571 windows in the cycle, rather than forward. It returns @code{nil}. | 564 windows in the cycle, rather than forward. It returns @code{nil}. |
565 | |
566 The argument @var{all-frames} has the same meaning is as in | |
567 @code{next-window}, but the @var{minibuf} argument of @code{next-window} | |
568 is always effectively @code{nil}. | |
572 | 569 |
573 In an interactive call, @var{count} is the numeric prefix argument. | 570 In an interactive call, @var{count} is the numeric prefix argument. |
574 @end deffn | 571 @end deffn |
575 | 572 |
576 @c Emacs 19 feature | 573 @c Emacs 19 feature |
893 function, which should return a frame. The default value of the | 890 function, which should return a frame. The default value of the |
894 variable is a function that creates a frame using parameters from | 891 variable is a function that creates a frame using parameters from |
895 @code{pop-up-frame-alist}. | 892 @code{pop-up-frame-alist}. |
896 @end defvar | 893 @end defvar |
897 | 894 |
898 @defvar pop-up-frame-alist | 895 @defopt pop-up-frame-alist |
899 This variable holds an alist specifying frame parameters used when | 896 This variable holds an alist specifying frame parameters used when |
900 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for | 897 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for |
901 more information about frame parameters. | 898 more information about frame parameters. |
902 @end defvar | 899 @end defopt |
903 | 900 |
904 @defopt special-display-buffer-names | 901 @defopt special-display-buffer-names |
905 A list of buffer names for buffers that should be displayed specially. | 902 A list of buffer names for buffers that should be displayed specially. |
906 If the buffer's name is in this list, @code{display-buffer} handles the | 903 If the buffer's name is in this list, @code{display-buffer} handles the |
907 buffer specially. | 904 buffer specially. |
936 | 933 |
937 The default value of this variable is | 934 The default value of this variable is |
938 @code{special-display-popup-frame}. | 935 @code{special-display-popup-frame}. |
939 @end defvar | 936 @end defvar |
940 | 937 |
941 @defun special-display-popup-frame buffer | 938 @defun special-display-popup-frame buffer &rest args |
942 This function makes @var{buffer} visible in a frame of its own. If | 939 This function makes @var{buffer} visible in a frame of its own. If |
943 @var{buffer} is already displayed in a window in some frame, it makes | 940 @var{buffer} is already displayed in a window in some frame, it makes |
944 the frame visible and raises it, to use that window. Otherwise, it | 941 the frame visible and raises it, to use that window. Otherwise, it |
945 creates a frame that will be dedicated to @var{buffer}. | 942 creates a frame that will be dedicated to @var{buffer}. |
946 | 943 |
947 This function uses an existing window displaying @var{buffer} whether or | 944 If @var{args} is an alist, it specifies frame parameters for the new |
948 not it is in a frame of its own; but if you set up the above variables | 945 frame. |
949 in your init file, before @var{buffer} was created, then presumably the | 946 |
950 window was previously made by this function. | 947 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car |
948 @var{args})} is called as a function to actually create and set up the | |
949 frame; it is called with @var{buffer} as first argument, and @code{(cdr | |
950 @var{args})} as additional arguments. | |
951 | |
952 This function always uses an existing window displaying @var{buffer}, | |
953 whether or not it is in a frame of its own; but if you set up the above | |
954 variables in your init file, before @var{buffer} was created, then | |
955 presumably the window was previously made by this function. | |
951 @end defun | 956 @end defun |
952 | 957 |
953 @defopt special-display-frame-alist | 958 @defopt special-display-frame-alist |
954 This variable holds frame parameters for | 959 This variable holds frame parameters for |
955 @code{special-display-popup-frame} to use when it creates a frame. | 960 @code{special-display-popup-frame} to use when it creates a frame. |
1033 | 1038 |
1034 As far as the user is concerned, point is where the cursor is, and | 1039 As far as the user is concerned, point is where the cursor is, and |
1035 when the user switches to another buffer, the cursor jumps to the | 1040 when the user switches to another buffer, the cursor jumps to the |
1036 position of point in that buffer. | 1041 position of point in that buffer. |
1037 | 1042 |
1038 @defun window-point window | 1043 @defun window-point &optional window |
1039 This function returns the current position of point in @var{window}. | 1044 This function returns the current position of point in @var{window}. |
1040 For a nonselected window, this is the value point would have (in that | 1045 For a nonselected window, this is the value point would have (in that |
1041 window's buffer) if that window were selected. | 1046 window's buffer) if that window were selected. If @var{window} is |
1047 @code{nil}, the selected window is used. | |
1042 | 1048 |
1043 When @var{window} is the selected window and its buffer is also the | 1049 When @var{window} is the selected window and its buffer is also the |
1044 current buffer, the value returned is the same as point in that buffer. | 1050 current buffer, the value returned is the same as point in that buffer. |
1045 | 1051 |
1046 Strictly speaking, it would be more correct to return the | 1052 Strictly speaking, it would be more correct to return the |
1079 When you create a window, or display a different buffer in it, the | 1085 When you create a window, or display a different buffer in it, the |
1080 display-start position is set to a display-start position recently used | 1086 display-start position is set to a display-start position recently used |
1081 for the same buffer, or 1 if the buffer doesn't have any. | 1087 for the same buffer, or 1 if the buffer doesn't have any. |
1082 | 1088 |
1083 Redisplay updates the window-start position (if you have not specified | 1089 Redisplay updates the window-start position (if you have not specified |
1084 it explicitly since the previous redisplay) so that point appears on the | 1090 it explicitly since the previous redisplay)---for example, to make sure |
1085 screen. Nothing except redisplay automatically changes the window-start | 1091 point appears on the screen. Nothing except redisplay automatically |
1086 position; if you move point, do not expect the window-start position to | 1092 changes the window-start position; if you move point, do not expect the |
1087 change in response until after the next redisplay. | 1093 window-start position to change in response until after the next |
1094 redisplay. | |
1088 | 1095 |
1089 For a realistic example of using @code{window-start}, see the | 1096 For a realistic example of using @code{window-start}, see the |
1090 description of @code{count-lines} in @ref{Text Lines}. | 1097 description of @code{count-lines} in @ref{Text Lines}. |
1091 @end defun | 1098 @end defun |
1092 | 1099 |
1186 @end example | 1193 @end example |
1187 | 1194 |
1188 The @code{pos-visible-in-window-p} function considers only vertical | 1195 The @code{pos-visible-in-window-p} function considers only vertical |
1189 scrolling. If @var{position} is out of view only because @var{window} | 1196 scrolling. If @var{position} is out of view only because @var{window} |
1190 has been scrolled horizontally, @code{pos-visible-in-window-p} returns | 1197 has been scrolled horizontally, @code{pos-visible-in-window-p} returns |
1191 @code{t}. @xref{Horizontal Scrolling}. | 1198 @code{t} anyway. @xref{Horizontal Scrolling}. |
1192 @end defun | 1199 @end defun |
1193 | 1200 |
1194 @node Vertical Scrolling | 1201 @node Textual Scrolling |
1195 @section Vertical Scrolling | 1202 @section Textual Scrolling |
1196 @cindex vertical scrolling | 1203 @cindex textual scrolling |
1197 @cindex scrolling vertically | 1204 @cindex scrolling textually |
1198 | 1205 |
1199 Vertical scrolling means moving the text up or down in a window. It | 1206 @dfn{Textual scrolling} means moving the text up or down though a |
1200 works by changing the value of the window's display-start location. It | 1207 window. It works by changing the value of the window's display-start |
1201 may also change the value of @code{window-point} to keep it on the | 1208 location. It may also change the value of @code{window-point} to keep |
1202 screen. | 1209 point on the screen. |
1210 | |
1211 Textual scrolling was formerly called ``vertical scrolling,'' but we | |
1212 changed its name to distinguish it from the new vertical fractional | |
1213 scrolling feature (@pxref{Vertical Scrolling}). | |
1203 | 1214 |
1204 In the commands @code{scroll-up} and @code{scroll-down}, the directions | 1215 In the commands @code{scroll-up} and @code{scroll-down}, the directions |
1205 ``up'' and ``down'' refer to the motion of the text in the buffer at which | 1216 ``up'' and ``down'' refer to the motion of the text in the buffer at which |
1206 you are looking through the window. Imagine that the text is | 1217 you are looking through the window. Imagine that the text is |
1207 written on a long roll of paper and that the scrolling commands move the | 1218 written on a long roll of paper and that the scrolling commands move the |
1216 text in the buffer, but it is less like what the user sees. The | 1227 text in the buffer, but it is less like what the user sees. The |
1217 position of a window on the terminal does not move, and short scrolling | 1228 position of a window on the terminal does not move, and short scrolling |
1218 commands clearly move the text up or down on the screen. We have chosen | 1229 commands clearly move the text up or down on the screen. We have chosen |
1219 names that fit the user's point of view. | 1230 names that fit the user's point of view. |
1220 | 1231 |
1221 The scrolling functions (aside from @code{scroll-other-window}) have | 1232 The textual scrolling functions (aside from |
1222 unpredictable results if the current buffer is different from the buffer | 1233 @code{scroll-other-window}) have unpredictable results if the current |
1223 that is displayed in the selected window. @xref{Current Buffer}. | 1234 buffer is different from the buffer that is displayed in the selected |
1235 window. @xref{Current Buffer}. | |
1224 | 1236 |
1225 @deffn Command scroll-up &optional count | 1237 @deffn Command scroll-up &optional count |
1226 This function scrolls the text in the selected window upward | 1238 This function scrolls the text in the selected window upward |
1227 @var{count} lines. If @var{count} is negative, scrolling is actually | 1239 @var{count} lines. If @var{count} is negative, scrolling is actually |
1228 downward. | 1240 downward. |
1249 @deffn Command scroll-other-window &optional count | 1261 @deffn Command scroll-other-window &optional count |
1250 This function scrolls the text in another window upward @var{count} | 1262 This function scrolls the text in another window upward @var{count} |
1251 lines. Negative values of @var{count}, or @code{nil}, are handled | 1263 lines. Negative values of @var{count}, or @code{nil}, are handled |
1252 as in @code{scroll-up}. | 1264 as in @code{scroll-up}. |
1253 | 1265 |
1254 You can specify a buffer to scroll with the variable | 1266 You can specify which buffer to scroll by setting the variable |
1255 @code{other-window-scroll-buffer}. When the selected window is the | 1267 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't |
1256 minibuffer, the next window is normally the one at the top left corner. | 1268 already displayed, @code{scroll-other-window} displays it in some |
1257 You can specify a different window to scroll with the variable | 1269 window. |
1270 | |
1271 When the selected window is the minibuffer, the next window is normally | |
1272 the one at the top left corner. You can specify a different window to | |
1273 scroll, when the minibuffer is selected, by setting the variable | |
1258 @code{minibuffer-scroll-window}. This variable has no effect when any | 1274 @code{minibuffer-scroll-window}. This variable has no effect when any |
1259 other window is selected. @xref{Minibuffer Misc}. | 1275 other window is selected. @xref{Minibuffer Misc}. |
1260 | 1276 |
1261 When the minibuffer is active, it is the next window if the selected | 1277 When the minibuffer is active, it is the next window if the selected |
1262 window is the one at the bottom right corner. In this case, | 1278 window is the one at the bottom right corner. In this case, |
1351 (global-set-key [kp-multiply] 'line-to-top-of-window) | 1367 (global-set-key [kp-multiply] 'line-to-top-of-window) |
1352 @end group | 1368 @end group |
1353 @end example | 1369 @end example |
1354 @end deffn | 1370 @end deffn |
1355 | 1371 |
1372 @node Vertical Scrolling | |
1373 @section Vertical Fractional Scrolling | |
1374 @cindex Vertical Fractional Scrolling | |
1375 | |
1376 @dfn{Vertical fractional scrolling} means shifting the image in the | |
1377 window up or down by a specified multiple or fraction of a line. | |
1378 Starting in Emacs 21, each window has a @dfn{vertical scroll position}, | |
1379 which is a number, never less than zero. It specifies how far to raise | |
1380 the contents of the window. Raising the window contents generally makes | |
1381 all or part of some lines disappear off the top, and all or part of some | |
1382 other lines appear at the bottom. The usual value is zero. | |
1383 | |
1384 The vertical scroll position is measured in units of the normal line | |
1385 height, which is the height of the default font. Thus, if the value is | |
1386 .5, that means the window contents are scrolled up half the normal line | |
1387 height. If it is 3.3, that means the window contents are scrolled up | |
1388 somewhat over three times the normal line height. | |
1389 | |
1390 What fraction of a line the vertical scrolling covers, or how many | |
1391 lines, depends on what the lines contain. A value of .5 could scroll a | |
1392 line whose height is very short off the screen, while a value of 3.3 | |
1393 could scroll just part of the way through a tall line or an image. | |
1394 | |
1395 @defun window-vscroll &optional window | |
1396 This function returns the current vertical scroll position of | |
1397 @var{window}, If @var{window} is @code{nil}, the selected window is | |
1398 used. | |
1399 | |
1400 @example | |
1401 @group | |
1402 (window-vscroll) | |
1403 @result{} 0 | |
1404 @end group | |
1405 @end example | |
1406 @end defun | |
1407 | |
1408 @defun set-window-vscroll window lines | |
1409 This function sets @var{window}'s vertical scroll position to | |
1410 @var{lines}. The argument @var{lines} should be zero or positive; if | |
1411 not, it is taken as zero. | |
1412 | |
1413 The actual vertical scroll position must always correspond | |
1414 to an integral number of pixels, so the value you specify | |
1415 is rounded accordingly. | |
1416 | |
1417 The return value is the result of this rounding. | |
1418 | |
1419 @example | |
1420 @group | |
1421 (set-window-vscroll (selected-window) 1.2) | |
1422 @result{} 1.13 | |
1423 @end group | |
1424 @end example | |
1425 @end defun | |
1426 | |
1356 @node Horizontal Scrolling | 1427 @node Horizontal Scrolling |
1357 @section Horizontal Scrolling | 1428 @section Horizontal Scrolling |
1358 @cindex horizontal scrolling | 1429 @cindex horizontal scrolling |
1359 | 1430 |
1360 Because we read English from left to right in the ``inner loop'', and | 1431 @dfn{Horizontal scrolling} means shifting the image in the window left |
1361 from top to bottom in the ``outer loop'', horizontal scrolling is not | 1432 or right by a specified multiple of the normal character width. Each |
1362 like vertical scrolling. Vertical scrolling involves selection of a | 1433 window has a @dfn{vertical scroll position}, which is a number, never |
1363 contiguous portion of text to display, but horizontal scrolling causes | 1434 less than zero. It specifies how far to shift the contents left. |
1364 part of each line to go off screen. The amount of horizontal scrolling | 1435 Shifting the window contents left generally makes all or part of some |
1365 is therefore specified as a number of columns rather than as a position | 1436 characters disappear off the left, and all or part of some other |
1366 in the buffer. It has nothing to do with the display-start position | 1437 characters appear at the right. The usual value is zero. |
1367 returned by @code{window-start}. | 1438 |
1439 The horizontal scroll position is measured in units of the normal | |
1440 character width, which is the width of space in the default font. Thus, | |
1441 if the value is 5, that means the window contents are scrolled left by 5 | |
1442 times the the normal character width. How many characters actually | |
1443 disappear off to the left depends on their width, and could vary from | |
1444 line to line. | |
1445 | |
1446 Because we read from side to side in the ``inner loop'', and from top | |
1447 to bottom in the ``outer loop'', the effect of horizontal scrolling is | |
1448 not like that of textual or vertical scrolling. Textual scrolling | |
1449 involves selection of a portion of text to display, and vertical | |
1450 scrolling moves the window contents contiguously; but horizontal | |
1451 scrolling causes part of @emph{each line} to go off screen. | |
1368 | 1452 |
1369 Usually, no horizontal scrolling is in effect; then the leftmost | 1453 Usually, no horizontal scrolling is in effect; then the leftmost |
1370 column is at the left edge of the window. In this state, scrolling to | 1454 column is at the left edge of the window. In this state, scrolling to |
1371 the right is meaningless, since there is no data to the left of the | 1455 the right is meaningless, since there is no data to the left of the edge |
1372 screen to be revealed by it; so this is not allowed. Scrolling to the | 1456 to be revealed by it; so this is not allowed. Scrolling to the left is |
1373 left is allowed; it scrolls the first columns of text off the edge of | 1457 allowed; it scrolls the first columns of text off the edge of the window |
1374 the window and can reveal additional columns on the right that were | 1458 and can reveal additional columns on the right that were truncated |
1375 truncated before. Once a window has a nonzero amount of leftward | 1459 before. Once a window has a nonzero amount of leftward horizontal |
1376 horizontal scrolling, you can scroll it back to the right, but only so | 1460 scrolling, you can scroll it back to the right, but only so far as to |
1377 far as to reduce the net horizontal scroll to zero. There is no limit | 1461 reduce the net horizontal scroll to zero. There is no limit to how far |
1378 to how far left you can scroll, but eventually all the text will | 1462 left you can scroll, but eventually all the text will disappear off the |
1379 disappear off the left edge. | 1463 left edge. |
1380 | 1464 |
1381 @deffn Command scroll-left count | 1465 In Emacs 21, redisplay automatically alters the horizontal scrolling |
1466 of a window as necessary to ensure that point is always visible. | |
1467 However, you can still set the horizontal scrolling value explicitly. | |
1468 The value you specify will be used, provided it leaves point visible. | |
1469 | |
1470 @deffn Command scroll-left &optional count | |
1382 This function scrolls the selected window @var{count} columns to the | 1471 This function scrolls the selected window @var{count} columns to the |
1383 left (or to the right if @var{count} is negative). The return value is | 1472 left (or to the right if @var{count} is negative). The default |
1384 the total amount of leftward horizontal scrolling in effect after the | 1473 for @var{count} is the window width, minus 2. |
1385 change---just like the value returned by @code{window-hscroll} (below). | 1474 |
1386 @end deffn | 1475 The return value is the total amount of leftward horizontal scrolling in |
1387 | 1476 effect after the change---just like the value returned by |
1388 @deffn Command scroll-right count | 1477 @code{window-hscroll} (below). |
1478 @end deffn | |
1479 | |
1480 @deffn Command scroll-right &optional count | |
1389 This function scrolls the selected window @var{count} columns to the | 1481 This function scrolls the selected window @var{count} columns to the |
1390 right (or to the left if @var{count} is negative). The return value is | 1482 right (or to the left if @var{count} is negative). The default |
1391 the total amount of leftward horizontal scrolling in effect after the | 1483 for @var{count} is the window width, minus 2. |
1392 change---just like the value returned by @code{window-hscroll} (below). | 1484 |
1485 The return value is the total amount of leftward horizontal scrolling in | |
1486 effect after the change---just like the value returned by | |
1487 @code{window-hscroll} (below). | |
1393 | 1488 |
1394 Once you scroll a window as far right as it can go, back to its normal | 1489 Once you scroll a window as far right as it can go, back to its normal |
1395 position where the total leftward scrolling is zero, attempts to scroll | 1490 position where the total leftward scrolling is zero, attempts to scroll |
1396 any farther right have no effect. | 1491 any farther right have no effect. |
1397 @end deffn | 1492 @end deffn |
1424 | 1519 |
1425 @defun set-window-hscroll window columns | 1520 @defun set-window-hscroll window columns |
1426 This function sets the number of columns from the left margin that | 1521 This function sets the number of columns from the left margin that |
1427 @var{window} is scrolled from the value of @var{columns}. The argument | 1522 @var{window} is scrolled from the value of @var{columns}. The argument |
1428 @var{columns} should be zero or positive; if not, it is taken as zero. | 1523 @var{columns} should be zero or positive; if not, it is taken as zero. |
1524 Fractional values of @var{columns} are not supported at present. | |
1429 | 1525 |
1430 The value returned is @var{columns}. | 1526 The value returned is @var{columns}. |
1431 | 1527 |
1432 @example | 1528 @example |
1433 @group | 1529 @group |
1514 @var{bottom})}, all elements relative to 0, 0 at the top left corner of | 1610 @var{bottom})}, all elements relative to 0, 0 at the top left corner of |
1515 the frame. The element @var{right} of the value is one more than the | 1611 the frame. The element @var{right} of the value is one more than the |
1516 rightmost column used by @var{window}, and @var{bottom} is one more than | 1612 rightmost column used by @var{window}, and @var{bottom} is one more than |
1517 the bottommost row used by @var{window} and its mode-line. | 1613 the bottommost row used by @var{window} and its mode-line. |
1518 | 1614 |
1519 When you have side-by-side windows, the right edge value for a window | 1615 If a window has a scroll bar, the right edge value includes the width of |
1520 with a neighbor on the right includes the width of the separator between | 1616 the scroll bar. Otherwise, if the window has a neighbor on the right, |
1521 the window and that neighbor. This separator may be a column of | 1617 its right edge value includes the width of the separator line between |
1522 @samp{|} characters or it may be a scroll bar. Since the width of the | 1618 the window and that neighbor. Since the width of the window does not |
1523 window does not include this separator, the width does not equal the | 1619 include this separator, the width does not usually equal the difference |
1524 difference between the right and left edges in this case. | 1620 between the right and left edges. |
1525 | 1621 |
1526 Here is the result obtained on a typical 24-line terminal with just one | 1622 Here is the result obtained on a typical 24-line terminal with just one |
1527 window: | 1623 window: |
1528 | 1624 |
1529 @example | 1625 @example |
1536 @noindent | 1632 @noindent |
1537 The bottom edge is at line 23 because the last line is the echo area. | 1633 The bottom edge is at line 23 because the last line is the echo area. |
1538 | 1634 |
1539 If @var{window} is at the upper left corner of its frame, then | 1635 If @var{window} is at the upper left corner of its frame, then |
1540 @var{bottom} is the same as the value of @code{(window-height)}, | 1636 @var{bottom} is the same as the value of @code{(window-height)}, |
1541 @var{right} is almost the same as the value of | 1637 @var{right} is almost the same as the value of @code{(window-width)}, |
1542 @code{(window-width)}@footnote{They are not exactly equal because | 1638 and @var{top} and @var{left} are zero. For example, the edges of the |
1543 @var{right} includes the vertical separator line or scroll bar, while | 1639 following window are @w{@samp{0 0 8 5}}. Assuming that the frame has |
1544 @code{(window-width)} does not.}, and @var{top} and @var{left} are zero. | 1640 more than 8 columns, the last column of the window (column 7) holds a |
1545 For example, the edges of the following window are @w{@samp{0 0 5 8}}. | 1641 border rather than text. The last row (row 4) holds the mode line, |
1546 Assuming that the frame has more than 8 columns, the last column of the | 1642 shown here with @samp{xxxxxxxxx}. |
1547 window (column 7) holds a border rather than text. The last row (row 4) | |
1548 holds the mode line, shown here with @samp{xxxxxxxxx}. | |
1549 | 1643 |
1550 @example | 1644 @example |
1551 @group | 1645 @group |
1552 0 | 1646 0 |
1553 _______ | 1647 _______ |
1559 | 1653 |
1560 7 | 1654 7 |
1561 @end group | 1655 @end group |
1562 @end example | 1656 @end example |
1563 | 1657 |
1564 When there are side-by-side windows, any window not at the right edge of | |
1565 its frame has a separator in its last column or columns. The separator | |
1566 counts as one or two columns in the width of the window. A window never | |
1567 includes a separator on its left, since that belongs to the window to | |
1568 the left. | |
1569 | |
1570 In the following example, let's suppose that the frame is 7 | 1658 In the following example, let's suppose that the frame is 7 |
1571 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} | 1659 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} |
1572 and the edges of the right window are @w{@samp{4 0 7 3}}. | 1660 and the edges of the right window are @w{@samp{4 0 8 3}}. |
1573 | 1661 |
1574 @example | 1662 @example |
1575 @group | 1663 @group |
1576 ___ ___ | 1664 ___ ___ |
1577 | | | | 1665 | | | |
1608 | 1696 |
1609 If the requested size would exceed that of the window's frame, then the | 1697 If the requested size would exceed that of the window's frame, then the |
1610 function makes the window occupy the entire height (or width) of the | 1698 function makes the window occupy the entire height (or width) of the |
1611 frame. | 1699 frame. |
1612 | 1700 |
1701 If there are various other windows from which lines or columns can be | |
1702 stolen, and some of them specify fixed size (using | |
1703 @code{window-size-fixed}, see below), they are left untouched while | |
1704 other windows are ``robbed.'' If it would be necessary to alter the | |
1705 size of a fixed-size window, @code{enlarge-window} gets an error | |
1706 instead. | |
1707 | |
1613 If @var{size} is negative, this function shrinks the window by | 1708 If @var{size} is negative, this function shrinks the window by |
1614 @minus{}@var{size} lines or columns. If that makes the window smaller | 1709 @minus{}@var{size} lines or columns. If that makes the window smaller |
1615 than the minimum size (@code{window-min-height} and | 1710 than the minimum size (@code{window-min-height} and |
1616 @code{window-min-width}), @code{enlarge-window} deletes the window. | 1711 @code{window-min-width}), @code{enlarge-window} deletes the window. |
1617 | 1712 |
1650 (shrink-window columns t)) | 1745 (shrink-window columns t)) |
1651 @end group | 1746 @end group |
1652 @end example | 1747 @end example |
1653 @end deffn | 1748 @end deffn |
1654 | 1749 |
1655 @deffn Command shrink-window-if-larger-than-buffer window | 1750 @deffn Command shrink-window-if-larger-than-buffer &optional window |
1656 This command shrinks @var{window} to be as small as possible while still | 1751 This command shrinks @var{window} to be as small as possible while still |
1657 showing the full contents of its buffer---but not less than | 1752 showing the full contents of its buffer---but not less than |
1658 @code{window-min-height} lines. | 1753 @code{window-min-height} lines. If @var{window} is not given, |
1754 it defaults to the selected window. | |
1659 | 1755 |
1660 However, the command does nothing if the window is already too small to | 1756 However, the command does nothing if the window is already too small to |
1661 display the whole text of the buffer, or if part of the contents are | 1757 display the whole text of the buffer, or if part of the contents are |
1662 currently scrolled off screen, or if the window is not the full width of | 1758 currently scrolled off screen, or if the window is not the full width of |
1663 its frame, or if the window is the only window in its frame. | 1759 its frame, or if the window is the only window in its frame. |
1664 @end deffn | 1760 @end deffn |
1761 | |
1762 @tindex window-size-fixed | |
1763 @defvar window-size-fixed | |
1764 If this variable is non-@code{nil}, in any given buffer, | |
1765 then the size of any window displaying the buffer remains fixed | |
1766 unless you explicitly change it or Emacs has no other choice. | |
1767 (This feature is new in Emacs 21.) | |
1768 | |
1769 If the value is @code{height}, then only the window's height is fixed; | |
1770 if the value is @code{width}, then only the window's width is fixed. | |
1771 Any other non-@code{nil} value fixes both the width and the height. | |
1772 | |
1773 The usual way to use this variable is to give it a buffer-local value in | |
1774 a particular buffer. That way, the windows (but usually there is only | |
1775 one) displaying that buffer have fixed size. | |
1776 | |
1777 Explicit size-change functions such as @code{enlarge-window} | |
1778 get an error if they would have to change a window size which is fixed. | |
1779 Therefore, when you want to change the size of such a window, | |
1780 you should bind @code{window-size-fixed} to @code{nil}, like this: | |
1781 | |
1782 @example | |
1783 (let ((window-size-fixed nil)) | |
1784 (enlarge-window 10)) | |
1785 @end example | |
1786 | |
1787 Note that changing the frame size will change the size of a | |
1788 fixed-size window, if there is no other alternative. | |
1789 @end defvar | |
1665 | 1790 |
1666 @cindex minimum window size | 1791 @cindex minimum window size |
1667 The following two variables constrain the window-size-changing | 1792 The following two variables constrain the window-size-changing |
1668 functions to a minimum height and width. | 1793 functions to a minimum height and width. |
1669 | 1794 |
1719 window. | 1844 window. |
1720 | 1845 |
1721 @item mode-line | 1846 @item mode-line |
1722 The coordinates are in the mode line of @var{window}. | 1847 The coordinates are in the mode line of @var{window}. |
1723 | 1848 |
1724 @item vertical-split | 1849 @item header-line |
1850 The coordinates are in the header line of @var{window}. | |
1851 | |
1852 @item vertical-line | |
1725 The coordinates are in the vertical line between @var{window} and its | 1853 The coordinates are in the vertical line between @var{window} and its |
1726 neighbor to the right. This value occurs only if the window doesn't | 1854 neighbor to the right. This value occurs only if the window doesn't |
1727 have a scroll bar; positions in a scroll bar are considered outside the | 1855 have a scroll bar; positions in a scroll bar are considered outside the |
1728 window. | 1856 window for these purposes. |
1729 | 1857 |
1730 @item nil | 1858 @item nil |
1731 The coordinates are not in any part of @var{window}. | 1859 The coordinates are not in any part of @var{window}. |
1732 @end table | 1860 @end table |
1733 | 1861 |
1748 | 1876 |
1749 If you want to record all frames instead of just one, use a frame | 1877 If you want to record all frames instead of just one, use a frame |
1750 configuration instead of a window configuration. @xref{Frame | 1878 configuration instead of a window configuration. @xref{Frame |
1751 Configurations}. | 1879 Configurations}. |
1752 | 1880 |
1753 @defun current-window-configuration | 1881 @defun current-window-configuration &optional frame |
1754 This function returns a new object representing the selected frame's | 1882 This function returns a new object representing @var{frame}'s |
1755 current window configuration, including the number of windows, their | 1883 current window configuration, including the number of windows, their |
1756 sizes and current buffers, which window is the selected window, and for | 1884 sizes and current buffers, which window is the selected window, and for |
1757 each window the displayed buffer, the display-start position, and the | 1885 each window the displayed buffer, the display-start position, and the |
1758 positions of point and the mark. It also includes the values of | 1886 positions of point and the mark. It also includes the values of |
1759 @code{window-min-height}, @code{window-min-width} and | 1887 @code{window-min-height}, @code{window-min-width} and |
1760 @code{minibuffer-scroll-window}. An exception is made for point in the | 1888 @code{minibuffer-scroll-window}. An exception is made for point in the |
1761 current buffer, whose value is not saved. | 1889 current buffer, whose value is not saved. |
1890 | |
1891 If @var{frame} is omitted, the selected frame is used. | |
1762 @end defun | 1892 @end defun |
1763 | 1893 |
1764 @defun set-window-configuration configuration | 1894 @defun set-window-configuration configuration |
1765 This function restores the configuration of windows and buffers as | 1895 This function restores the configuration of windows and buffers as |
1766 specified by @var{configuration}. The argument @var{configuration} must | 1896 specified by @var{configuration}, for the frame that @var{configuration} |
1767 be a value that was previously returned by | 1897 was created for. |
1768 @code{current-window-configuration}. This configuration is restored in | 1898 |
1769 the frame from which @var{configuration} was made, whether that frame is | 1899 The argument @var{configuration} must be a value that was previously |
1770 selected or not. This always counts as a window size change and | 1900 returned by @code{current-window-configuration}. This configuration is |
1771 triggers execution of the @code{window-size-change-functions} | 1901 restored in the frame from which @var{configuration} was made, whether |
1902 that frame is selected or not. This always counts as a window size | |
1903 change and triggers execution of the @code{window-size-change-functions} | |
1772 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't | 1904 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't |
1773 know how to tell whether the new configuration actually differs from the | 1905 know how to tell whether the new configuration actually differs from the |
1774 old one. | 1906 old one. |
1775 | 1907 |
1776 If the frame which @var{configuration} was saved from is dead, all this | 1908 If the frame which @var{configuration} was saved from is dead, all this |
1911 @tindex set-window-redisplay-end-trigger | 2043 @tindex set-window-redisplay-end-trigger |
1912 This function sets @var{window}'s end trigger position at | 2044 This function sets @var{window}'s end trigger position at |
1913 @var{position}. | 2045 @var{position}. |
1914 @end defun | 2046 @end defun |
1915 | 2047 |
1916 @defun window-redisplay-end-trigger window | 2048 @defun window-redisplay-end-trigger &optional window |
1917 @tindex window-redisplay-end-trigger | 2049 @tindex window-redisplay-end-trigger |
1918 This function returns @var{window}'s current end trigger position. | 2050 This function returns @var{window}'s current end trigger position. |
1919 @end defun | 2051 @end defun |
1920 | 2052 |
1921 @defvar window-configuration-change-hook | 2053 @defvar window-configuration-change-hook |