Commit c638661f authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent 9faf445e
......@@ -37,7 +37,7 @@ displayed in windows.
@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 @@ one selected frame; and the window selected within that frame is
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 @@ the buffer it displays
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 @@ for example, you can move through a summary buffer in one window while
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 @@ screen into Emacs windows.
@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 @@ leftmost @var{size} columns, and gives the rest of the columns to the
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 @@ part of the documentation string):
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 @@ The selected window can be the least recently used window if it is the
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 @@ width). If there are no side-by-side windows, then this is the window
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 @@ the order is left to right, or top to bottom.
@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 @@ displays it in a window not currently selected. It then selects that
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 @@ for @var{buffer-or-name}, so that nothing needs to be done.
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 @@ is non-@code{nil}.
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 @@ This function makes @var{buffer} visible in a frame of its own. If
@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 @@ This function positions point in @var{window} at position
@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 @@ used. For example,
@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 @@ For a realistic example, see the description of @code{count-lines} in
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 @@ his is the contents of buffer foo.
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 @@ upward.
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 @@ moves off the screen. If the value is zero, then redisplay scrolls the
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 @@ prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
@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 @@ Replaces three keystroke sequence C-u 0 C-l."
(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 @@ disappear off the left edge.
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 @@ is off the screen due to horizontal scrolling:
@example
@group
(save-excursion
(goto-char @var{position})
(defun hscroll-on-screen (window position)
(save-excursion
(goto-char position)
(and
(>= (- (current-column) (window-hscroll @var{window})) 0)
(< (- (current-column) (window-hscroll @var{window}))
(window-width @var{window}))))
(>= (- (current-column) (window-hscroll window)) 0)
(< (- (current-column) (window-hscroll window))
(window-width window)))))
@end group
@end example
......@@ -1282,7 +1296,7 @@ is off the screen due to horizontal scrolling:
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 @@ window:
@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 @@ window size. Emacs does not permit overlapping windows or gaps between
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 @@ If @var{horizontal} is non-@code{nil}, this function makes
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 @@ It could be defined as follows:
@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 @@ before it is automatically deleted. Making a window smaller than
@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 @@ value below that is ignored. The default value is 10.
@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 @@ as @code{save-window-excursion}:
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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment