X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/5a36d8349df0f59c79a310b20a0966286560f557..17e5726d3b54cae3c791603ee0eebc547c8756f3:/lispref/windows.texi diff --git a/lispref/windows.texi b/lispref/windows.texi index a274688963..96f4d5af69 100644 --- a/lispref/windows.texi +++ b/lispref/windows.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, -@c 2004, 2005, 2006 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/windows @node Windows, Frames, Buffers, Top @@ -55,15 +55,11 @@ multiple nonoverlapping Emacs windows. In each frame, at any time, one and only one window is designated as @dfn{selected within the frame}. The frame's cursor appears in that window, but the other windows have ``non-selected'' cursors, normally -less visible. At any time, one frame is the selected frame; and the -window selected within that frame is @dfn{the selected window}. The -selected window's buffer is usually the current buffer (except when -@code{set-buffer} has been used). @xref{Current Buffer}. - -@defvar cursor-in-non-selected-windows -If this variable is @code{nil}, Emacs displays only one cursor, -in the selected window. Other windows have no cursor at all. -@end defvar +less visible. (@pxref{Cursor Parameters}, for customization of this.) +At any time, one frame is the selected frame; and the window selected +within that frame is @dfn{the selected window}. The selected window's +buffer is usually the current buffer (except when @code{set-buffer} +has been used). @xref{Current Buffer}. For practical purposes, a window exists only while it is displayed in a frame. Once removed from the frame, the window is effectively deleted @@ -161,10 +157,8 @@ The two ``halves'' of the split window initially display the same buffer previously visible in the window that was split. @deffn Command split-window &optional window size horizontal -This function splits @var{window} into two windows. The original -window @var{window} remains the selected window, but occupies only -part of its former screen area. The rest is occupied by a newly created -window which is returned as the value of this function. +This function splits a new window out of @var{window}'s screen area. +It returns the new window. If @var{horizontal} is non-@code{nil}, then @var{window} splits into two side by side windows. The original window @var{window} keeps the @@ -175,11 +169,13 @@ lines to the new window. The original window is therefore the 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 -split. If @var{size} is omitted or @code{nil}, then @var{window} is -divided evenly into two parts. (If there is an odd line, it is -allocated to the new window.) When @code{split-window} is called -interactively, all its arguments are @code{nil}. +If @var{window} is omitted or @code{nil}, that stands for the selected +window. When you split the selected window, it remains selected. + +If @var{size} is omitted or @code{nil}, then @var{window} is divided +evenly into two parts. (If there is an odd line, it is allocated to +the new window.) When @code{split-window} is called interactively, +all its arguments are @code{nil}. If splitting would result in making a window that is smaller than @code{window-min-height} or @code{window-min-width}, the function @@ -430,7 +426,7 @@ This function always returns @code{nil}. @node Selecting Windows @section Selecting Windows -@cindex selecting windows +@cindex selecting a window When a window is selected, the buffer in the window becomes the current buffer, and the cursor will appear in it. @@ -572,7 +568,7 @@ In general, within each set of siblings at any level in the window tree, the order is left to right, or top to bottom. @defun next-window &optional window minibuf all-frames -@cindex minibuffer window +@cindex minibuffer window, and @code{next-window} This function returns the window following @var{window} in the cyclic 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 @@ -1195,6 +1191,7 @@ point and the buffer's point always move together; they remain equal. @noindent @xref{Positions}, for more details on buffer positions. +@cindex cursor As far as the user is concerned, point is where the cursor is, and when the user switches to another buffer, the cursor jumps to the position of point in that buffer. @@ -1223,6 +1220,7 @@ this simply does @code{goto-char}. @node Window Start @section The Window Start Position +@cindex window start position Each window contains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position @@ -1231,6 +1229,15 @@ is called the @dfn{display-start} position of the window (or just the at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line. + After switching windows or buffers, and in some other cases, if the +window start is in the middle of a line, Emacs adjusts the window +start to the start of a line. This prevents certain operations from +leaving the window start at a meaningless point within a line. This +feature may interfere with testing some Lisp code by executing it +using the commands of Lisp mode, because they trigger this +readjustment. To test such code, put it into a command and bind the +command to a key. + @defun window-start &optional window @cindex window top line This function returns the display-start position of window @@ -1298,10 +1305,10 @@ However, if you specify the start position with this function using screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window. -For example, if point @w{is 1} and you set the start of the window @w{to -2}, then point would be ``above'' the top of the window. The display -routines will automatically move point if it is still 1 when redisplay -occurs. Here is an example: +For example, if point @w{is 1} and you set the start of the window +@w{to 37}, the start of the next line, point will be ``above'' the top +of the window. The display routines will automatically move point if +it is still 1 when redisplay occurs. Here is an example: @example @group @@ -1323,15 +1330,17 @@ occurs. Here is an example: @group (set-window-start (selected-window) - (1+ (window-start))) -@result{} 2 + (save-excursion + (goto-char 1) + (forward-line 1) + (point))) +@result{} 37 @end group @group ;; @r{Here is what @samp{foo} looks like after executing} ;; @r{the @code{set-window-start} expression.} ---------- Buffer: foo ---------- -his is the contents of buffer foo. 2 3 @point{}4 @@ -1355,6 +1364,9 @@ visible unless @var{partially} is non-@code{nil}. The argument @var{position} defaults to the current position of point in @var{window}; @var{window}, to the selected window. +If @var{position} is @code{t}, that means to check the last visible +position in @var{window}. + The @code{pos-visible-in-window-p} function considers only vertical scrolling. If @var{position} is out of view only because @var{window} has been scrolled horizontally, @code{pos-visible-in-window-p} returns @@ -1362,13 +1374,16 @@ non-@code{nil} anyway. @xref{Horizontal Scrolling}. If @var{position} is visible, @code{pos-visible-in-window-p} returns @code{t} if @var{partially} is @code{nil}; if @var{partially} is -non-@code{nil}, it returns a list of the form @code{(@var{x} @var{y} -@var{partial})}, where @var{x} and @var{y} are the pixel coordinates -relative to the top left corner of the window, and @var{partial} is -@code{nil} if the character after @var{position} is fully visible; -otherwise it is a cons @code{(@var{rtop} . @var{rbot})} where the -@var{rtop} and @var{rbot} specify the number of invisible pixels at -the top and bottom of the row at @var{position}. +non-@code{nil}, and the character after @var{position} is fully +visible, it returns a list of the form @code{(@var{x} @var{y})}, where +@var{x} and @var{y} are the pixel coordinates relative to the top left +corner of the window; otherwise it returns an extended list of the +form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} +@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number +of off-window pixels at the top and bottom of the row at +@var{position}, @var{rowh} specifies the visible height of that row, +and @var{vpos} specifies the vertical position (zero-based row number) +of that row. Here is an example: @@ -1382,6 +1397,30 @@ Here is an example: @end example @end defun +@defun window-line-height &optional line window +This function returns information about text line @var{line} in @var{window}. +If @var{line} is one of @code{header-line} or @code{mode-line}, +@code{window-line-height} returns information about the corresponding +line of the window. Otherwise, @var{line} is a text line number +starting from 0. A negative number counts from the end of the window. +The argument @var{line} defaults to the current line in @var{window}; +@var{window}, to the selected window. + +If the display is not up to date, @code{window-line-height} returns +@code{nil}. In that case, @code{pos-visible-in-window-p} may be used +to obtain related information. + +If there is no line corresponding to the specified @var{line}, +@code{window-line-height} returns @code{nil}. Otherwise, it returns +a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, +where @var{height} is the height in pixels of the visible part of the +line, @var{vpos} and @var{ypos} are the vertical position in lines and +pixels of the line relative to the top of the first text line, and +@var{offbot} is the number of off-window pixels at the bottom of the +text line. If there are off-window pixels at the top of the (first) +text line, @var{ypos} is negative. +@end defun + @node Textual Scrolling @section Textual Scrolling @cindex textual scrolling @@ -1474,7 +1513,7 @@ window is the one at the bottom right corner. In this case, @code{scroll-other-window} attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message -``Beginning of buffer''. +@samp{Beginning of buffer}. @end deffn @c Emacs 19 feature @@ -1506,7 +1545,6 @@ never happens. @end defopt @defopt scroll-down-aggressively -@tindex scroll-down-aggressively The value of this variable should be either @code{nil} or a fraction @var{f} between 0 and 1. If it is a fraction, that specifies where on the screen to put point when scrolling down. More precisely, when a @@ -1521,7 +1559,6 @@ fashion. @end defopt @defopt scroll-up-aggressively -@tindex scroll-up-aggressively Likewise, for scrolling up. The value, @var{f}, specifies how far point should be placed from the bottom of the window; thus, as with @code{scroll-up-aggressively}, a larger value scrolls more aggressively. @@ -1593,7 +1630,7 @@ Replaces three keystroke sequence C-u 0 C-l." @node Vertical Scrolling @section Vertical Fractional Scrolling -@cindex Vertical Fractional Scrolling +@cindex vertical fractional scrolling @dfn{Vertical fractional scrolling} means shifting the image in the window up or down by a specified multiple or fraction of a line. @@ -1678,8 +1715,8 @@ times the normal character width. How many characters actually disappear off to the left depends on their width, and could vary from line to line. - Because we read from side to side in the ``inner loop'', and from top -to bottom in the ``outer loop'', the effect of horizontal scrolling is + Because we read from side to side in the ``inner loop,'' and from top +to bottom in the ``outer loop,'' the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal @@ -1835,7 +1872,6 @@ If @var{window} is @code{nil}, the function uses the selected window. @end example @end defun -@tindex window-body-height @defun window-body-height &optional window Like @code{window-height} but the value does not include the mode line (if any) or the header line (if any). @@ -1858,6 +1894,12 @@ If @var{window} is @code{nil}, the function uses the selected window. @end example @end defun +@defun window-full-width-p &optional window +This function returns non-@code{nil} if @var{window} is as wide as +the frame that contains it; otherwise @code{nil}. +If @var{window} is @code{nil}, the function uses the selected window. +@end defun + @defun window-edges &optional window This function returns a list of the edge coordinates of @var{window}. If @var{window} is @code{nil}, the selected window is used. @@ -1958,6 +2000,7 @@ in character lines and columns. @node Resizing Windows @section Changing the Size of a Window @cindex window resizing +@cindex resize window @cindex changing window size @cindex window size, changing @@ -2068,7 +2111,6 @@ This command returns non-@code{nil} if it actually shrank the window and @code{nil} otherwise. @end deffn -@tindex window-size-fixed @defvar window-size-fixed If this variable is non-@code{nil}, in any given buffer, then the size of any window displaying the buffer remains fixed @@ -2211,13 +2253,13 @@ similar to the value returned by @code{window-edges}. @cindex saving window information A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, what -part of each buffer is displayed, and the values of point and the -mark; also their fringes, margins, and scroll bar settings. It also +frame---all windows, their sizes, which buffers they contain, how +those buffers are scrolled, and their values of point and the mark; +also their fringes, margins, and scroll bar settings. It also includes the values of @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. An -exception is made for point in the selected window for the current -buffer; its value is not saved in the window configuration. +@code{window-min-width} and @code{minibuffer-scroll-window}. As a +special exception, the window configuration does not record the value +of point in the selected window for the current buffer. You can bring back an entire previous layout by restoring a window configuration previously saved. If you want to record all frames @@ -2329,6 +2371,7 @@ configurations. @node Window Hooks @section Hooks for Window Scrolling and Changes +@cindex hooks for window operations This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. @@ -2348,6 +2391,10 @@ Displaying a different buffer in the window also runs these functions. These functions must be careful in using @code{window-end} (@pxref{Window Start}); if you need an up-to-date value, you must use the @var{update} argument to ensure you get it. + +@strong{Warning:} don't use this feature to alter the way the window +is scrolled. It's not designed for that, and such use probably won't +work. @end defvar @defvar window-size-change-functions