Mercurial > emacs
changeset 8491:320375e58ee3
*** empty log message ***
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Tue, 09 Aug 1994 04:23:51 +0000 |
| parents | 7db23bef024e |
| children | 865daa7a9faf |
| files | lispref/windows.texi |
| diffstat | 1 files changed, 67 insertions(+), 50 deletions(-) [+] |
line wrap: on
line diff
--- a/lispref/windows.texi Tue Aug 09 03:57:21 1994 +0000 +++ b/lispref/windows.texi Tue Aug 09 04:23:51 1994 +0000 @@ -37,7 +37,7 @@ @cindex selected window A @dfn{window} is the physical area of the screen in which a buffer is -displayed. The term is also used to refer to a Lisp object which +displayed. The term is also used to refer to a Lisp object that represents that screen area in Emacs Lisp. It should be clear from the context which is meant. @@ -49,7 +49,7 @@ current buffer (except when @code{set-buffer} has been used). @xref{Current Buffer}. - For all intents, a window only exists while it is displayed on the + For practical purposes, a window exists only while it is displayed on the terminal. Once removed from the display, the window is effectively deleted and should not be used, @emph{even though there may still be references to it} from other Lisp objects. Restoring a saved window @@ -78,7 +78,7 @@ position within the buffer at the upper left of the window @item -the amount of horizontal scrolling, in columns +amount of horizontal scrolling, in columns @item point @@ -98,7 +98,7 @@ the other window shows messages one at a time as they are reached. The meaning of ``window'' in Emacs is similar to what it means in the -context of general purpose window systems such as X, but not identical. +context of general-purpose window systems such as X, but not identical. The X Window System subdivides the screen into X windows; Emacs uses one or more X windows, called @dfn{frames} in Emacs terminology, and subdivides each of them into (nonoverlapping) Emacs windows. When you @@ -110,7 +110,7 @@ @cindex tiled windows Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are @dfn{tiled}; they never overlap, and -together they fill the whole of the screen or frame. Because of the way +together they fill the whole screen or frame. Because of the way in which Emacs creates new windows and resizes them, you can't create every conceivable tiling of windows on an Emacs frame. @xref{Splitting Windows}, and @ref{Size of Window}. @@ -148,7 +148,7 @@ new window. Otherwise, it splits into windows one above the other, and @var{window} keeps the upper @var{size} lines and gives the rest of the lines to the new window. The original window is therefore the -right-hand or upper of the two, and the new window is the left-hand or +left-hand or upper of the two, and the new window is the right-hand or lower. If @var{window} is omitted or @code{nil}, then the selected window is @@ -278,7 +278,7 @@ This function returns non-@code{nil} if there is only one window. The argument @var{no-mini}, if non-@code{nil}, means don't count the minibuffer even if it is active; otherwise, the minibuffer window is -included, if active, in the total number of windows which is compared +included, if active, in the total number of windows, which is compared against one. The argument @var{all-frames} specifies which frames to consider. Here @@ -412,8 +412,7 @@ only window. A newly created window becomes the least recently used window until it is selected. A minibuffer window is never a candidate. -The argument @var{frame} controls which set of windows are -considered. +The argument @var{frame} controls which windows are considered. @itemize @bullet @item @@ -433,7 +432,7 @@ with the most lines. A minibuffer window is never a candidate. If there are two windows of the same size, then the function returns -the window which is first in the cyclic ordering of windows (see +the window that is first in the cyclic ordering of windows (see following section), starting from the selected window. The argument @var{frame} controls which set of windows are @@ -467,8 +466,8 @@ @defun next-window &optional window minibuf all-frames @cindex minibuffer window This function returns the window following @var{window} in the cyclic -ordering of windows. This is the window which @kbd{C-x o} would select -if done when @var{window} is selected. If @var{window} is the only +ordering of windows. This is the window that @kbd{C-x o} would select +if typed when @var{window} is selected. If @var{window} is the only window visible, then this function returns @var{window}. If omitted, @var{window} defaults to the selected window. @@ -674,11 +673,11 @@ window. The handling of the buffer is the same as in @code{switch-to-buffer}. -The previously selected window is absolutely never used to display the -buffer. If it is the only window, then it is split to make a distinct -window for this purpose. If the selected window is already displaying -the buffer, then it continues to do so, but another window is -nonetheless found to display it in as well. +The currently selected window is absolutely never used to do the job. +If it is the only window, then it is split to make a distinct window for +this purpose. If the selected window is already displaying the buffer, +then it continues to do so, but another window is nonetheless found to +display it in as well. @end deffn @defun pop-to-buffer buffer-or-name &optional other-window @@ -712,15 +711,12 @@ If @var{buffer-or-name} is a string that does not name an existing buffer, a buffer by that name is created. - -An example use of this function is found at the end of @ref{Filter -Functions}. @end defun @node Choosing Window @section Choosing a Window for Display - This section describes the basic facility which chooses a window to + This section describes the basic facility that chooses a window to display a buffer in---@code{display-buffer}. All the higher-level functions and commands use this subroutine. Here we describe how to use @code{display-buffer} and how to customize it. @@ -783,7 +779,7 @@ Its value should be a function of no arguments. When @code{display-buffer} makes a new frame, it does so by calling that function, which should return a frame. The default value of the -variable is a function which creates a frame using parameters from +variable is a function that creates a frame using parameters from @code{pop-up-frame-alist}. @end defvar @@ -824,6 +820,11 @@ @var{buffer} is already displayed in a window in some frame, it makes the frame visible and raises it, to use that window. Otherwise, it creates a frame that will be dedicated to @var{buffer}. + +This function uses an existing window displaying @var{buffer} whether or +not it is in a frame of its own; but if you set up the above variables +in your init file, before @var{buffer} was created, then presumably the +window was previously made by this function. @end defun @defopt special-display-frame-alist @@ -918,7 +919,7 @@ @section The Window Start Position Each window contains a marker used to keep track of a buffer position -which specifies where in the buffer display should start. This position +that specifies where in the buffer display should start. This position is called the @dfn{display-start} position of the window (or just the @dfn{start}). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not @@ -937,7 +938,7 @@ @end group @end example -When you create a window, or display a different buffer in it, the the +When you create a window, or display a different buffer in it, the display-start position is set to a display-start position recently used for the same buffer, or 1 if the buffer doesn't have any. @@ -949,11 +950,25 @@ This function returns the position of the end of the display in window @var{window}. If @var{window} is @code{nil}, the selected window is used. + +If the last redisplay of @var{window} was preempted, and did not finish, +Emacs does not know the position of the end of display in that window; +in that case, this function returns @code{nil}. You can compute where +the end of the window @emph{would} have been, if redisplay had finished, +like this: + +@example +(save-excursion + (goto-char (window-start window)) + (vertical-motion (1- (window-height window)) + window) + (point)) +@end example @end defun @defun set-window-start window position &optional noforce This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. +@var{position} in @var{window}'s buffer. It returns @var{position}. The display routines insist that the position of point be visible when a buffer is displayed. Normally, they change the display-start position @@ -1010,8 +1025,6 @@ If @var{noforce} is non-@code{nil}, and @var{position} would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus @var{position} is not used. - -This function returns @var{position}. @end defun @defun pos-visible-in-window-p &optional position window @@ -1085,7 +1098,7 @@ If @var{count} is omitted or @code{nil}, then the length of the scroll is @code{next-screen-context-lines} lines less than the usable height of -the window. +the window (not counting its mode line). @code{scroll-down} returns @code{nil}. @end deffn @@ -1126,7 +1139,7 @@ text to center point vertically in the window. If the value is a positive integer @var{n}, then redisplay brings point back on screen by scrolling @var{n} lines in either direction, if possible; otherwise, it -centers point if possible. The default value is zero. +centers point. The default value is zero. @end defopt @defopt next-screen-context-lines @@ -1159,9 +1172,9 @@ @var{count} to 4, which positions the current line four lines from the top. -Typing @kbd{C-u 0 C-l} positions the current line at the top of the -window. This action is so handy that some people bind the command to a -function key. For example, +With an argument of zero, @code{recenter} positions the current line at +the top of the window. This action is so handy that some people make a +separate key binding to do this. For example, @example @group @@ -1171,7 +1184,7 @@ (interactive) (recenter 0)) -(global-set-key "\C-cl" 'line-to-top-of-window) +(global-set-key [kp-multiply] 'line-to-top-of-window) @end group @end example @end deffn @@ -1204,14 +1217,14 @@ This function scrolls the selected window @var{count} columns to the left (or to the right if @var{count} is negative). The return value is the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll}. +change---just like the value returned by @code{window-hscroll} (below). @end deffn @deffn Command scroll-right count This function scrolls the selected window @var{count} columns to the right (or to the left if @var{count} is negative). The return value is the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll}. +change---just like the value returned by @code{window-hscroll} (below). Once you scroll a window as far right as it can go, back to its normal position where the total leftward scrolling is zero, attempts to scroll @@ -1264,12 +1277,13 @@ @example @group -(save-excursion - (goto-char @var{position}) - (and - (>= (- (current-column) (window-hscroll @var{window})) 0) - (< (- (current-column) (window-hscroll @var{window})) - (window-width @var{window})))) +(defun hscroll-on-screen (window position) + (save-excursion + (goto-char position) + (and + (>= (- (current-column) (window-hscroll window)) 0) + (< (- (current-column) (window-hscroll window)) + (window-width window))))) @end group @end example @@ -1282,7 +1296,7 @@ the height (the number of lines) and the width (the number of character positions in each line). The mode line is included in the height. But the width does not count the scroll bar or the column of @samp{|} -characters separates side-by-side windows. +characters that separates side-by-side windows. The following three functions return size information about a window: @@ -1354,6 +1368,9 @@ @end group @end example +@noindent +The bottom edge is at line 23 because the last line is the echo area. + If @var{window} is at the upper left corner of its frame, @var{right} and @var{bottom} are the same as the values returned by @code{(window-width)} and @code{(window-height)} respectively, and @@ -1411,7 +1428,7 @@ windows, so resizing one window affects other windows. @deffn Command enlarge-window size &optional horizontal -This function makes the selected window @var{size} lines bigger, +This function makes the selected window @var{size} lines taller, stealing lines from neighboring windows. It takes the lines from one window at a time until that window is used up, then takes from another. If a window from which lines are stolen shrinks below @@ -1422,9 +1439,9 @@ lines. If a window from which columns are stolen shrinks below @code{window-min-width} columns, that window disappears. -If the window's frame is smaller than @var{size} lines (or columns), -then the function makes the window occupy the entire height (or width) -of the frame. +If the requested size would exceed that of the window's frame, then the +function makes the window occupy the entire height (or width) of the +frame. If @var{size} is negative, this function shrinks the window by @minus{}@var{size} lines or columns. If that makes the window smaller @@ -1469,7 +1486,7 @@ @end deffn @cindex minimum window size - The following two variables constrain the window size changing + The following two variables constrain the window-size-changing functions to a minimum height and width. @defopt window-min-height @@ -1478,7 +1495,7 @@ @code{window-min-height} automatically deletes it, and no window may be created shorter than this. The absolute minimum height is two (allowing one line for the mode line, and one line for the buffer display). -Actions which change window sizes reset this variable to two if it is +Actions that change window sizes reset this variable to two if it is less than two. The default value is 4. @end defopt @@ -1493,7 +1510,7 @@ @node Coordinates and Windows @section Coordinates and Windows -This section describes how to compare screen coordinates with windows. +This section describes how to relate screen coordinates to windows. @defun window-at x y &optional frame This function returns the window containing the specified cursor @@ -1594,7 +1611,7 @@ This special form records the window configuration, executes @var{forms} in sequence, then restores the earlier window configuration. The window configuration includes the value of point and the portion of the buffer -which is visible. It also includes the choice of selected window. +that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use @code{save-excursion} if you wish to preserve that.