X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-26;h=967198484fb30012bf0fd99beec724e959db1660;hb=2779fcb5d524d6b7de5a6ef9ebfd6662433a4a07;hp=d580a61a3e5b04d69ebd7cc1a3c8414957f4ac08;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-26 b/info/lispref.info-26 index d580a61..9671984 100644 --- a/info/lispref.info-26 +++ b/info/lispref.info-26 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1149 +50,1172 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows +File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers -Windows and Point -================= +Creating Buffers +================ - Each window has its own value of point, independent of the value of -point in other windows displaying the same buffer. This makes it useful -to have multiple windows showing one buffer. + This section describes the two primitives for creating buffers. +`get-buffer-create' creates a buffer if it finds no existing buffer +with the specified name; `generate-new-buffer' always creates a new +buffer and gives it a unique name. - * The window point is established when a window is first created; it - is initialized from the buffer's point, or from the window point - of another window opened on the buffer if such a window exists. + Other functions you can use to create buffers include +`with-output-to-temp-buffer' (*note Temporary Displays::) and +`create-file-buffer' (*note Visiting Files::). Starting a subprocess +can also create a buffer (*note Processes::). - * Selecting a window sets the value of point in its buffer to the - window's value of point. Conversely, deselecting a window sets - the window's value of point from that of the buffer. Thus, when - you switch between windows that display a given buffer, the point - value for the selected window is in effect in the buffer, while - the point values for the other windows are stored in those windows. + - Function: get-buffer-create name + This function returns a buffer named NAME. It returns an existing + buffer with that name, if one exists; otherwise, it creates a new + buffer. The buffer does not become the current buffer--this + function does not change which buffer is current. - * As long as the selected window displays the current buffer, the - window's point and the buffer's point always move together; they - remain equal. + An error is signaled if NAME is not a string. - * *Note Positions::, for more details on buffer positions. + (get-buffer-create "foo") + => # - 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. + The major mode for the new buffer is set to Fundamental mode. The + variable `default-major-mode' is handled at a higher level. *Note + Auto Major Mode::. - - Function: window-point window - This function returns the current position of point in WINDOW. - For a nonselected window, this is the value point would have (in - that window's buffer) if that window were selected. + - Function: generate-new-buffer name + This function returns a newly created, empty buffer, but does not + make it current. If there is no buffer named NAME, then that is + the name of the new buffer. If that name is in use, this function + adds suffixes of the form `' to NAME, where N is an integer. + It tries successive integers starting with 2 until it finds an + available name. - When WINDOW is the selected window and its buffer is also the - current buffer, the value returned is the same as point in that - buffer. + An error is signaled if NAME is not a string. - Strictly speaking, it would be more correct to return the - "top-level" value of point, outside of any `save-excursion' forms. - But that value is hard to find. + (generate-new-buffer "bar") + => # + (generate-new-buffer "bar") + => #> + (generate-new-buffer "bar") + => #> - - Function: set-window-point window position - This function positions point in WINDOW at position POSITION in - WINDOW's buffer. + The major mode for the new buffer is set to Fundamental mode. The + variable `default-major-mode' is handled at a higher level. *Note + Auto Major Mode::. + + See the related function `generate-new-buffer-name' in *Note + Buffer Names::.  -File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows - -The 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 -is called the "display-start" position of the window (or just the -"start"). The character after this position is the one that appears at -the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - - - Function: window-start &optional window - This function returns the display-start position of window WINDOW. - If WINDOW is `nil', the selected window is used. For example, - - (window-start) - => 7058 - - 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. - - For a realistic example, see the description of `count-lines' in - *Note Text Lines::. - - - Function: window-end &optional window - This function returns the position of the end of the display in - window WINDOW. If WINDOW is `nil', the selected window is used. - - Simply changing the buffer text or moving point does not update the - value that `window-end' returns. The value is updated only when - Emacs redisplays and redisplay actually finishes. - - If the last redisplay of 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 a value that is not - correct. In a future version, `window-end' will return `nil' in - that case. - - - Function: set-window-start window position &optional noforce - This function sets the display-start position of WINDOW to - POSITION in WINDOW's buffer. It returns POSITION. - - The display routines insist that the position of point be visible - when a buffer is displayed. Normally, they change the - display-start position (that is, scroll the window) whenever - necessary to make point visible. However, if you specify the - start position with this function using `nil' for NOFORCE, it - means you want display to start at POSITION even if that would put - the location of point off the 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 is 1 and you set the start of the window - 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: - - ;; Here is what `foo' looks like before executing - ;; the `set-window-start' expression. - - ---------- Buffer: foo ---------- - -!-This is the contents of buffer foo. - 2 - 3 - 4 - 5 - 6 - ---------- Buffer: foo ---------- +File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers + +Killing Buffers +=============== + + "Killing a buffer" makes its name unknown to XEmacs and makes its +text space available for other use. + + The buffer object for the buffer that has been killed remains in +existence as long as anything refers to it, but it is specially marked +so that you cannot make it current or display it. Killed buffers retain +their identity, however; two distinct buffers, when killed, remain +distinct according to `eq'. + + If you kill a buffer that is current or displayed in a window, XEmacs +automatically selects or displays some other buffer instead. This means +that killing a buffer can in general change the current buffer. +Therefore, when you kill a buffer, you should also take the precautions +associated with changing the current buffer (unless you happen to know +that the buffer being killed isn't current). *Note Current Buffer::. + + If you kill a buffer that is the base buffer of one or more indirect +buffers, the indirect buffers are automatically killed as well. + + The `buffer-name' of a killed buffer is `nil'. To test whether a +buffer has been killed, you can either use this feature or the function +`buffer-live-p'. + + - Function: buffer-live-p object + This function returns `t' if OBJECT is an editor buffer that has + not been deleted, `nil' otherwise. + + - Command: kill-buffer buffer-or-name + This function kills the buffer BUFFER-OR-NAME, freeing all its + memory for use as space for other buffers. (Emacs version 18 and + older was unable to return the memory to the operating system.) + It returns `nil'. The argument BUFFER-OR-NAME may be a buffer or + the name of one. + + Any processes that have this buffer as the `process-buffer' are + sent the `SIGHUP' signal, which normally causes them to terminate. + (The basic meaning of `SIGHUP' is that a dialup line has been + disconnected.) *Note Deleting Processes::. + + If the buffer is visiting a file and contains unsaved changes, + `kill-buffer' asks the user to confirm before the buffer is killed. + It does this even if not called interactively. To prevent the + request for confirmation, clear the modified flag before calling + `kill-buffer'. *Note Buffer Modification::. + + Killing a buffer that is already dead has no effect. + + (kill-buffer "foo.unchanged") + => nil + (kill-buffer "foo.changed") - (set-window-start - (selected-window) - (1+ (window-start))) - => 2 + ---------- Buffer: Minibuffer ---------- + Buffer foo.changed modified; kill anyway? (yes or no) yes + ---------- Buffer: Minibuffer ---------- - ;; Here is what `foo' looks like after executing - ;; the `set-window-start' expression. - ---------- Buffer: foo ---------- - his is the contents of buffer foo. - 2 - 3 - -!-4 - 5 - 6 - ---------- Buffer: foo ---------- - - If NOFORCE is non-`nil', and 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 POSITION is not used. - - - Function: pos-visible-in-window-p &optional position window - This function returns `t' if POSITION is within the range of text - currently visible on the screen in WINDOW. It returns `nil' if - POSITION is scrolled vertically out of view. The argument - POSITION defaults to the current position of point; WINDOW, to the - selected window. Here is an example: - - (or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) - - The `pos-visible-in-window-p' function considers only vertical - scrolling. If POSITION is out of view only because WINDOW has - been scrolled horizontally, `pos-visible-in-window-p' returns `t'. - *Note Horizontal Scrolling::. + => nil + + - Variable: kill-buffer-query-functions + After confirming unsaved changes, `kill-buffer' calls the functions + in the list `kill-buffer-query-functions', in order of appearance, + with no arguments. The buffer being killed is the current buffer + when they are called. The idea is that these functions ask for + confirmation from the user for various nonstandard reasons. If + any of them returns `nil', `kill-buffer' spares the buffer's life. + + - Variable: kill-buffer-hook + This is a normal hook run by `kill-buffer' after asking all the + questions it is going to ask, just before actually killing the + buffer. The buffer to be killed is current when the hook + functions run. *Note Hooks::. + + - Variable: buffer-offer-save + This variable, if non-`nil' in a particular buffer, tells + `save-buffers-kill-emacs' and `save-some-buffers' to offer to save + that buffer, just as they offer to save file-visiting buffers. The + variable `buffer-offer-save' automatically becomes buffer-local + when set for any reason. *Note Buffer-Local Variables::.  -File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows - -Vertical Scrolling -================== - - Vertical scrolling means moving the text up or down in a window. It -works by changing the value of the window's display-start location. It -may also change the value of `window-point' to keep it on the screen. - - In the commands `scroll-up' and `scroll-down', the directions "up" -and "down" refer to the motion of the text in the buffer at which you -are looking through the window. Imagine that the text is written on a -long roll of paper and that the scrolling commands move the paper up -and down. Thus, if you are looking at text in the middle of a buffer -and repeatedly call `scroll-down', you will eventually see the -beginning of the buffer. - - Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -"down" commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The scrolling functions (aside from `scroll-other-window') have -unpredictable results if the current buffer is different from the buffer -that is displayed in the selected window. *Note Current Buffer::. - - - Command: scroll-up &optional count - This function scrolls the text in the selected window upward COUNT - lines. If COUNT is negative, scrolling is actually downward. - - If COUNT is `nil' (or omitted), then the length of scroll is - `next-screen-context-lines' lines less than the usable height of - the window (not counting its modeline). - - `scroll-up' returns `nil'. - - - Command: scroll-down &optional count - This function scrolls the text in the selected window downward - COUNT lines. If COUNT is negative, scrolling is actually upward. - - If COUNT is omitted or `nil', then the length of the scroll is - `next-screen-context-lines' lines less than the usable height of - the window (not counting its mode line). - - `scroll-down' returns `nil'. - - - Command: scroll-other-window &optional count - This function scrolls the text in another window upward COUNT - lines. Negative values of COUNT, or `nil', are handled as in - `scroll-up'. - - You can specify a buffer to scroll with the variable - `other-window-scroll-buffer'. When the selected window is the - minibuffer, the next window is normally the one at the top left - corner. You can specify a different window to scroll with the - variable `minibuffer-scroll-window'. This variable has no effect - when any other window is selected. *Note Minibuffer Misc::. - - When the minibuffer is active, it is the next window if the - selected window is the one at the bottom right corner. In this - case, `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". - - - Variable: other-window-scroll-buffer - If this variable is non-`nil', it tells `scroll-other-window' - which buffer to scroll. - - - User Option: scroll-step - This variable controls how scrolling is done automatically when - point 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 N, then redisplay brings point back on - screen by scrolling N lines in either direction, if possible; - otherwise, it centers point. The default value is zero. - - - User Option: scroll-conservatively - This variable controls how many lines Emacs tries to scroll before - recentering. If you set it to a small number, then when you move - point a short distance off the screen, XEmacs will scroll the - screen just far enough to bring point back on screen, provided - that does not exceed `scroll-conservatively' lines. This variable - overrides the redisplay preemption. - - - User Option: next-screen-context-lines - The value of this variable is the number of lines of continuity to - retain when scrolling by full screens. For example, `scroll-up' - with an argument of `nil' scrolls so that this many lines at the - bottom of the window appear instead at the top. The default value - is `2'. - - - Command: recenter &optional count - This function scrolls the selected window to put the text where - point is located at a specified vertical position within the - window. +File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers - If COUNT is a nonnegative number, it puts the line containing - point COUNT lines down from the top of the window. If COUNT is a - negative number, then it counts upward from the bottom of the - window, so that -1 stands for the last usable line in the window. - If COUNT is a non-`nil' list, then it stands for the line in the - middle of the window. - - If COUNT is `nil', `recenter' puts the line containing point in - the middle of the window, then clears and redisplays the entire - selected frame. - - When `recenter' is called interactively, COUNT is the raw prefix - argument. Thus, typing `C-u' as the prefix sets the COUNT to a - non-`nil' list, while typing `C-u 4' sets COUNT to 4, which - positions the current line four lines from the top. - - With an argument of zero, `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, - - (defun line-to-top-of-window () - "Scroll current line to top of window. - Replaces three keystroke sequence C-u 0 C-l." - (interactive) - (recenter 0)) - - (global-set-key [kp-multiply] 'line-to-top-of-window) +Indirect Buffers +================ - -File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows - -Horizontal Scrolling -==================== - - Because we read English first from top to bottom and second from left -to right, horizontal scrolling is not like vertical scrolling. Vertical -scrolling involves selection of a contiguous portion of text to display. -Horizontal scrolling causes part of each line to go off screen. The -amount of horizontal scrolling is therefore specified as a number of -columns rather than as a position in the buffer. It has nothing to do -with the display-start position returned by `window-start'. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the -screen to be revealed by it; so this is not allowed. Scrolling to the -left is allowed; it scrolls the first columns of text off the edge of -the window and can reveal additional columns on the right that were -truncated before. Once a window has a nonzero amount of leftward -horizontal scrolling, you can scroll it back to the right, but only so -far as to reduce the net horizontal scroll to zero. There is no limit -to how far left you can scroll, but eventually all the text will -disappear off the left edge. - - - Command: scroll-left count - This function scrolls the selected window COUNT columns to the - left (or to the right if 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 `window-hscroll' - (below). - - - Command: scroll-right count - This function scrolls the selected window COUNT columns to the - right (or to the left if 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 `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 any farther right have no effect. - - - Function: window-hscroll &optional window - This function returns the total leftward horizontal scrolling of - WINDOW--the number of columns by which the text in WINDOW is - scrolled left past the left margin. - - The value is never negative. It is zero when no horizontal - scrolling has been done in WINDOW (which is usually the case). - - If WINDOW is `nil', the selected window is used. - - (window-hscroll) - => 0 - (scroll-left 5) - => 5 - (window-hscroll) - => 5 - - - Function: set-window-hscroll window columns - This function sets the number of columns from the left margin that - WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS - should be zero or positive; if not, it is taken as zero. - - The value returned is COLUMNS. - - (set-window-hscroll (selected-window) 10) - => 10 - - Here is how you can determine whether a given position POSITION is -off the screen due to horizontal scrolling: - - (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))))) + An "indirect buffer" shares the text of some other buffer, which is +called the "base buffer" of the indirect buffer. In some ways it is +the analogue, for buffers, of a symbolic link among files. The base +buffer may not itself be an indirect buffer. One base buffer may have +several "indirect children". - -File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows - -The Size of a Window -==================== - - An Emacs window is rectangular, and its size information consists of -the height (in lines or pixels) and the width (in character positions -or pixels). The modeline is included in the height. The pixel width -and height values include scrollbars and margins, while the -line/character-position values do not. - - Note that the height in lines, and the width in characters, are -determined by dividing the corresponding pixel value by the height or -width of the default font in that window (if this is a variable-width -font, the average width is used). The resulting values may or may not -represent the actual number of lines in the window, or the actual number -of character positions in any particular line, esp. if there are pixmaps -or various different fonts in the window. - - The following functions return size information about a window: - - - Function: window-height &optional window - This function returns the number of lines in WINDOW, including its - modeline but not including the horizontal scrollbar, if any (this - is different from `window-pixel-height'). If WINDOW is `nil', the - function uses the selected window. - - (window-height) - => 40 - (split-window-vertically) - => # - (window-height) - => 20 - - - Function: window-width &optional window - This function returns the number of columns in WINDOW, not - including any left margin, right margin, or vertical scrollbar - (this is different from `window-pixel-width'). If WINDOW is - `nil', the function uses the selected window. - - (window-width) - => 80 - (window-height) - => 40 - (split-window-horizontally) - => # - (window-width) - => 39 - - Note that after splitting the window into two side-by-side windows, -the width of each window is less the half the width of the original -window because a vertical scrollbar appeared between the windows, -occupying two columns worth of space. Also, the height shrunk by one -because horizontal scrollbars appeared that weren't there before. -(Horizontal scrollbars appear only when lines are truncated, not when -they wrap. This is usually the case for horizontally split windows but -not for full-frame windows. You can change this using the variables -`truncate-lines' and `truncate-partial-width-windows'.) - - - Function: window-pixel-height &optional window - This function returns the height of WINDOW in pixels, including - its modeline and horizontal scrollbar, if any. If WINDOW is - `nil', the function uses the selected window. - - (window-pixel-height) - => 600 - (split-window-vertically) - => # - (window-pixel-height) - => 300 - - - Function: window-pixel-width &optional window - This function returns the width of WINDOW in pixels, including any - left margin, right margin, or vertical scrollbar that may be - displayed alongside it. If WINDOW is `nil', the function uses the - selected window. + The text of the indirect buffer is always identical to the text of +its base buffer; changes made by editing either one are visible +immediately in the other. - (window-pixel-width) - => 735 - (window-pixel-height) - => 600 - (split-window-horizontally) - => # - (window-pixel-width) - => 367 - (window-pixel-height) - => 600 - - - Function: window-text-area-pixel-height &optional window - This function returns the height in pixels of the text displaying - portion of WINDOW, which defaults to the selected window. Unlike - `window-pixel-height', the space occupied by the modeline and - horizontal scrollbar, if any, is not counted. - - - Function: window-text-area-pixel-width &optional window - This function returns the width in pixels of the text displaying - portion of WINDOW, which defaults to the selected window. Unlike - `window-pixel-width', the space occupied by the vertical scrollbar - and divider, if any, is not counted. - - - Function: window-displayed-text-pixel-height &optional window - noclipped - This function returns the height in pixels of the text displayed in - WINDOW, which defaults to the selected window. Unlike - `window-text-area-pixel-height', any blank space below the end of - the buffer is not included. If optional argument NOCLIPPED is - non-`nil', any space occupied by clipped lines will not be - included. + But in all other respects, the indirect buffer and its base buffer +are completely separate. They have different names, different values of +point and mark, different narrowing, different markers and extents +(though inserting or deleting text in either buffer relocates the +markers and extents for both), different major modes, and different +local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not +automatically share text properties among themselves and their base +buffer. - -File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows - -The Position of a Window -======================== - - XEmacs provides functions to determine the absolute location of -windows within a frame, and the relative location of a window in -comparison to other windows in the same frame. - - - Function: window-pixel-edges &optional window - This function returns a list of the pixel edge coordinates of - WINDOW. If WINDOW is `nil', the selected window is used. - - The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements - relative to 0, 0 at the top left corner of the frame. The element - RIGHT of the value is one more than the rightmost pixel used by - WINDOW (including any left margin, right margin, or vertical - scrollbar displayed alongside it), and BOTTOM is one more than the - bottommost pixel used by WINDOW (including any modeline or - horizontal scrollbar displayed above or below it). The frame area - does not include any frame menubars or toolbars that may be - displayed; thus, for example, if there is only one window on the - frame, the values for LEFT and TOP will always be 0. - - If WINDOW is at the upper left corner of its frame, RIGHT and - BOTTOM are the same as the values returned by - `(window-pixel-width)' and `(window-pixel-height)' respectively, - and TOP and BOTTOM are zero. - - There is no longer a function `window-edges' because it does not -make sense in a world with variable-width and variable-height lines, as -are allowed in XEmacs. - - - Function: window-highest-p window - This function returns non-`nil' if WINDOW is along the top of its - frame. + An indirect buffer cannot visit a file, but its base buffer can. If +you try to save the indirect buffer, that actually works by saving the +base buffer. - - Function: window-lowest-p window - This function returns non-`nil' if WINDOW is along the bottom of - its frame. + Killing an indirect buffer has no effect on its base buffer. Killing +the base buffer kills all its indirect children. - - Function: window-text-area-pixel-edges &optional window - This function allows one to determine the location of the - text-displaying portion of WINDOW, which defaults to the selected - window, with respect to the top left corner of the window. It - returns a list of integer pixel positions `(left top right - bottom)', all relative to `(0,0)' at the top left corner of the - window. + - Command: make-indirect-buffer base-buffer name + This creates an indirect buffer named NAME whose base buffer is + BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string. - -File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows + If BASE-BUFFER is an indirect buffer, its base buffer is used as + the base for the new buffer. -Changing the Size of a Window -============================= + (make-indirect-buffer "*scratch*" "indirect") + => # - The window size functions fall into two classes: high-level commands -that change the size of windows and low-level functions that access -window size. XEmacs does not permit overlapping windows or gaps between -windows, so resizing one window affects other windows. - - - Command: enlarge-window size &optional horizontal window - This function makes the selected window 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 - `window-min-height' lines, that window disappears. - - If HORIZONTAL is non-`nil', this function makes WINDOW wider by - SIZE columns, stealing columns instead of lines. If a window from - which columns are stolen shrinks below `window-min-width' columns, - that window disappears. - - 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 SIZE is negative, this function shrinks the window by -SIZE - lines or columns. If that makes the window smaller than the - minimum size (`window-min-height' and `window-min-width'), - `enlarge-window' deletes the window. - - If WINDOW is non-`nil', it specifies a window to change instead of - the selected window. - - `enlarge-window' returns `nil'. - - - Command: enlarge-window-horizontally columns - This function makes the selected window COLUMNS wider. It could - be defined as follows: - - (defun enlarge-window-horizontally (columns) - (enlarge-window columns t)) - - - Command: enlarge-window-pixels count &optional side window - This function makes the selected window COUNT pixels larger. When - called from Lisp, optional second argument SIDE non-`nil' means to - grow sideways COUNT pixels, and optional third argument WINDOW - specifies the window to change instead of the selected window. - - - Command: shrink-window size &optional horizontal window - This function is like `enlarge-window' but negates the argument - SIZE, making the selected window smaller by giving lines (or - columns) to the other windows. If the window shrinks below - `window-min-height' or `window-min-width', then it disappears. - - If SIZE is negative, the window is enlarged by -SIZE lines or - columns. - - If WINDOW is non-`nil', it specifies a window to change instead of - the selected window. - - - Command: shrink-window-horizontally columns - This function makes the selected window COLUMNS narrower. It - could be defined as follows: - - (defun shrink-window-horizontally (columns) - (shrink-window columns t)) - - - Command: shrink-window-pixels count &optional side window - This function makes the selected window COUNT pixels smaller. - When called from Lisp, optional second argument SIDE non-`nil' - means to shrink sideways COUNT pixels, and optional third argument - WINDOW specifies the window to change instead of the selected - window. + - Function: buffer-base-buffer &optional buffer + This function returns the base buffer of BUFFER. If BUFFER is not + indirect, the value is `nil'. Otherwise, the value is another + buffer, which is never an indirect buffer. If BUFFER is not + supplied, it defaults to the current buffer. + + (buffer-base-buffer (get-buffer "indirect")) + => # - The following two variables constrain the window-size-changing -functions to a minimum height and width. - - - User Option: window-min-height - The value of this variable determines how short a window may become - before it is automatically deleted. Making a window smaller than - `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 that change window sizes reset this variable to - two if it is less than two. The default value is 4. - - - User Option: window-min-width - The value of this variable determines how narrow a window may - become before it automatically deleted. Making a window smaller - than `window-min-width' automatically deletes it, and no window - may be created narrower than this. The absolute minimum width is - one; any value below that is ignored. The default value is 10. - - - Variable: window-size-change-functions - This variable holds a list of functions to be called if the size - of any window changes for any reason. The functions are called - just once per redisplay, and just once for each frame on which - size changes have occurred. - - Each function receives the frame as its sole argument. There is no - direct way to find out which windows changed size, or precisely - how; however, if your size-change function keeps track, after each - change, of the windows that interest you, you can figure out what - has changed by comparing the old size data with the new. - - Creating or deleting windows counts as a size change, and therefore - causes these functions to be called. Changing the frame size also - counts, because it changes the sizes of the existing windows. - - It is not a good idea to use `save-window-excursion' in these - functions, because that always counts as a size change, and it - would cause these functions to be called over and over. In most - cases, `save-selected-window' is what you need here. + - Function: buffer-indirect-children &optional buffer + This function returns a list of all indirect buffers whose base + buffer is BUFFER. If BUFFER is indirect, the return value will + always be `nil'; see `make-indirect-buffer'. If BUFFER is not + supplied, it defaults to the current buffer. + + (buffer-indirect-children (get-buffer "*scratch*")) + => (#)  -File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows - -Window Configurations -===================== - - A "window configuration" records the entire layout of a frame--all -windows, their sizes, which buffers they contain, what part of each -buffer is displayed, and the values of point and the mark. You can -bring back an entire previous layout by restoring a window -configuration previously saved. - - If you want to record all frames instead of just one, use a frame -configuration instead of a window configuration. *Note Frame -Configurations::. - - - Function: current-window-configuration - This function returns a new object representing XEmacs's current - window configuration, namely the number of windows, their sizes - and current buffers, which window is the selected window, and for - each window the displayed buffer, the display-start position, and - the positions of point and the mark. An exception is made for - point in the current buffer, whose value is not saved. - - - Function: set-window-configuration configuration - This function restores the configuration of XEmacs's windows and - buffers to the state specified by CONFIGURATION. The argument - CONFIGURATION must be a value that was previously returned by - `current-window-configuration'. - - This function always counts as a window size change and triggers - execution of the `window-size-change-functions'. (It doesn't know - how to tell whether the new configuration actually differs from - the old one.) - - Here is a way of using this function to get the same effect as - `save-window-excursion': - - (let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-vertically nil) - ...) - (set-window-configuration config))) - - - Special Form: save-window-excursion forms... - This special form records the window configuration, executes FORMS - in sequence, then restores the earlier window configuration. The - window configuration includes the value of point and the portion - of the buffer 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 `save-excursion' if you wish to - preserve that. - - Don't use this construct when `save-selected-window' is all you - need. - - Exit from `save-window-excursion' always triggers execution of the - `window-size-change-functions'. (It doesn't know how to tell - whether the restored configuration actually differs from the one in - effect at the end of the FORMS.) - - The return value is the value of the final form in FORMS. For - example: - - (split-window) - => # - (setq w (selected-window)) - => # - (save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - => do-something - ;; The frame is now split again. +File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top - - Function: window-configuration-p object - This function returns `t' if OBJECT is a window configuration. +Windows +******* - Primitives to look inside of window configurations would make sense, -but none are implemented. It is not clear they are useful enough to be -worth implementing. + This chapter describes most of the functions and variables related to +Emacs windows. See *Note Display::, for information on how text is +displayed in windows. + +* Menu: + +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-lever functions for displaying a buffer + and choosing a window for it. +* Choosing Window:: How to choose a window for displaying a buffer. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Vertical Scrolling:: Moving text up and down in the window. +* Horizontal Scrolling:: Moving text sideways on the window. +* Size of Window:: Accessing the size of a window. +* Position of Window:: Accessing the position of a window. +* Resizing Windows:: Changing the size of a window. +* Window Configurations:: Saving and restoring the state of the screen.  -File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top +File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows -Frames -****** +Basic Concepts of Emacs Windows +=============================== - A FRAME is a rectangle on the screen that contains one or more -XEmacs windows. A frame initially contains a single main window (plus -perhaps a minibuffer window), which you can subdivide vertically or -horizontally into smaller windows. + A "window" in XEmacs is the physical area of the screen in which a +buffer is displayed. The term is also used to refer to a Lisp object +that represents that screen area in XEmacs Lisp. It should be clear +from the context which is meant. - When XEmacs runs on a text-only terminal, it starts with one "TTY -frame". If you create additional ones, XEmacs displays one and only -one at any given time--on the terminal screen, of course. + XEmacs groups windows into frames. A frame represents an area of +screen available for XEmacs to use. Each frame always contains at least +one window, but you can subdivide it vertically or horizontally into +multiple nonoverlapping Emacs windows. - When XEmacs communicates directly with an X server, it does not have -a TTY frame; instead, it starts with a single "X window frame". It can -display multiple X window frames at the same time, each in its own X -window. + In each frame, at any time, one and only one window is designated as +"selected within the frame". The frame's cursor appears in that +window. At ant time, one frame is the selected frame; and the window +selected within that frame is "the selected window". The selected +window's buffer is usually the current buffer (except when `set-buffer' +has been used). *Note Current Buffer::. - - Function: framep object - This predicate returns `t' if OBJECT is a frame, and `nil' - otherwise. + For practical purposes, a window exists only while it is displayed in +a frame. Once removed from the frame, the window is effectively deleted +and should not be used, _even though there may still be references to +it_ from other Lisp objects. Restoring a saved window configuration is +the only way for a window no longer on the screen to come back to life. +(*Note Deleting Windows::.) -* Menu: + Each window has the following attributes: + + * containing frame + + * window height + + * window width + + * window edges with respect to the frame or screen + + * the buffer it displays + + * position within the buffer at the upper left of the window -* Creating Frames:: Creating additional frames. -* Frame Properties:: Controlling frame size, position, font, etc. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. -* Frame Configurations:: Saving the state of all frames. -* Frame Hooks:: Hooks for customizing frame behavior. - - *Note Display::, for related information. + * amount of horizontal scrolling, in columns + + * point + + * the mark + + * how recently the window was selected + + Users create multiple windows so they can look at several buffers at +once. Lisp libraries use multiple windows for a variety of reasons, but +most often to display related information. In Rmail, 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 XEmacs is similar to what it means in the +context of general-purpose window systems such as X, but not identical. +The X Window System places X windows on the screen; XEmacs uses one or +more X windows as frames, and subdivides them into Emacs windows. When +you use XEmacs on a character-only terminal, XEmacs treats the whole +terminal screen as one frame. + + Most window systems support arbitrarily located overlapping windows. +In contrast, Emacs windows are "tiled"; they never overlap, and +together they fill the whole screen or frame. Because of the way in +which XEmacs creates new windows and resizes them, you can't create +every conceivable tiling of windows on an Emacs frame. *Note Splitting +Windows::, and *Note Size of Window::. + + *Note Display::, for information on how the contents of the window's +buffer are displayed in the window. + + - Function: windowp object + This function returns `t' if OBJECT is a window.  -File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames +File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows -Creating Frames -=============== +Splitting Windows +================= - To create a new frame, call the function `make-frame'. - - - Function: make-frame &optional props device - This function creates a new frame on DEVICE, if DEVICE permits - creation of frames. (An X server does; an ordinary terminal does - not (yet).) DEVICE defaults to the selected device if omitted. - *Note Consoles and Devices::. - - The argument PROPS is a property list (a list of alternating - keyword-value specifications) of properties for the new frame. (An - alist is accepted for backward compatibility but should not be - passed in.) Any properties not mentioned in PROPS default - according to the value of the variable `default-frame-plist'. For - X devices, properties not specified in `default-frame-plist' - default in turn from `default-x-frame-plist' and, if not specified - there, from the X resources. For TTY devices, - `default-tty-frame-plist' is consulted as well as - `default-frame-plist'. - - The set of possible properties depends in principle on what kind of - window system XEmacs uses to display its frames. *Note X Frame - Properties::, for documentation of individual properties you can - specify when creating an X window frame. + The functions described here are the primitives used to split a +window into two windows. Two higher level functions sometimes split a +window, but not always: `pop-to-buffer' and `display-buffer' (*note +Displaying Buffers::). + + The functions described here do not accept a buffer as an argument. +The two "halves" of the split window initially display the same buffer +previously visible in the window that was split. + + - Function: one-window-p &optional nomini which-frames which-devices + This function returns non-`nil' if there is only one window. The + argument NOMINI, if non-`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 against one. + + The remaining arguments controls which set of windows are counted, + as with `next-window'. + + - Command: split-window &optional window size horizontal + This function splits WINDOW into two windows. The original window + 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. + + If HORIZONTAL is non-`nil', then WINDOW splits into two side by + side windows. The original window WINDOW keeps the leftmost SIZE + columns, and gives the rest of the columns to the new window. + Otherwise, it splits into windows one above the other, and WINDOW + keeps the upper SIZE lines and gives the rest of the 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 WINDOW is omitted or `nil', then the selected window is split. + If SIZE is omitted or `nil', then WINDOW is divided evenly into + two parts. (If there is an odd line, it is allocated to the new + window.) When `split-window' is called interactively, all its + arguments are `nil'. + + The following example starts with one window on a frame that is 50 + lines high by 80 columns wide; then the window is split. + + (setq w (selected-window)) + => # + (window-edges) ; Edges in order: + => (0 0 80 50) ; left-top-right-bottom + + ;; Returns window created + (setq w2 (split-window w 15)) + => # + (window-edges w2) + => (0 15 80 50) ; Bottom window; + ; top is line 15 + (window-edges w) + => (0 0 80 15) ; Top window + + The frame looks like this: + + __________ + | | line 0 + | w | + |__________| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 + + Next, the top window is split horizontally: + + (setq w3 (split-window w 35 t)) + => # + (window-edges w3) + => (35 0 80 15) ; Left edge at column 35 + (window-edges w) + => (0 0 35 15) ; Right edge at column 35 + (window-edges w2) + => (0 15 80 50) ; Bottom window unchanged + + Now, the screen looks like this: + + column 35 + __________ + | | | line 0 + | w | w3 | + |___|______| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 + + Normally, Emacs indicates the border between two side-by-side + windows with a scroll bar (*note Scroll Bars: X Frame Properties.) + or `|' characters. The display table can specify alternative + border characters; see *Note Display Tables::. + + - Command: split-window-vertically &optional size + This function splits the selected window into two windows, one + above the other, leaving the selected window with SIZE lines. + + This function is simply an interface to `split-window'. Here is + the complete function definition for it: + + (defun split-window-vertically (&optional arg) + "Split current window into two windows, one above the other." + (interactive "P") + (split-window nil (and arg (prefix-numeric-value arg)))) + + - Command: split-window-horizontally &optional size + This function splits the selected window into two windows + side-by-side, leaving the selected window with SIZE columns. + + This function is simply an interface to `split-window'. Here is + the complete definition for `split-window-horizontally' (except for + part of the documentation string): + + (defun split-window-horizontally (&optional arg) + "Split selected window into two windows, side by side..." + (interactive "P") + (split-window nil (and arg (prefix-numeric-value arg)) t))  -File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames +File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows -Frame Properties +Deleting Windows ================ - A frame has many properties that control its appearance and behavior. -Just what properties a frame has depends on which display mechanism it -uses. + A window remains visible on its frame unless you "delete" it by +calling certain functions that delete windows. A deleted window cannot +appear on the screen, but continues to exist as a Lisp object until +there are no references to it. There is no way to cancel the deletion +of a window aside from restoring a saved window configuration (*note +Window Configurations::). Restoring a window configuration also +deletes any windows that aren't part of that configuration. - Frame properties exist for the sake of window systems. A terminal -frame has few properties, mostly for compatibility's sake; only the -height, width and `buffer-predicate' properties really do something. + When you delete a window, the space it took up is given to one +adjacent sibling. (In Emacs version 18, the space was divided evenly +among all the siblings.) -* Menu: + - Function: window-live-p window + This function returns `nil' if WINDOW is deleted, and `t' + otherwise. -* Property Access:: How to change a frame's properties. -* Initial Properties:: Specifying frame properties when you make a frame. -* X Frame Properties:: List of frame properties. -* Size and Position:: Changing the size and position of a frame. -* Frame Name:: The name of a frame (as opposed to its title). + *Warning:* Erroneous information or fatal errors may result from + using a deleted window as if it were live. - -File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties + - Command: delete-window &optional window force + This function removes WINDOW from the display. If WINDOW is + omitted, then the selected window is deleted. If window is the + only one on its frame, the frame is deleted as well. -Access to Frame Properties --------------------------- + Normally, you cannot delete the last non-minibuffer-only frame + (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error + is signaled instead. However, if optional second argument FORCE is + non-`nil', you can delete the last frame. (This will automatically + call `save-buffers-kill-emacs'.) - These functions let you read and change the properties of a frame. + This function returns `nil'. - - Function: frame-properties &optional frame - This function returns a plist listing all the properties of FRAME - and their values. + When `delete-window' is called interactively, the selected window + is deleted. - - Function: frame-property frame property &optional default - This function returns FRAME's value for the property PROPERTY. + - Command: delete-other-windows &optional window + This function makes WINDOW the only window on its frame, by + deleting the other windows in that frame. If WINDOW is omitted or + `nil', then the selected window is used by default. - - Function: set-frame-properties frame plist - This function alters the properties of frame FRAME based on the - elements of property list PLIST. If you don't mention a property - in PLIST, its value doesn't change. + The result is `nil'. - - Function: set-frame-property frame prop val - This function sets the property PROP of frame FRAME to the value - VAL. + - Command: delete-windows-on buffer &optional which-frames + which-devices + This function deletes all windows showing BUFFER. If there are no + windows showing BUFFER, it does nothing. - -File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties - -Initial Frame Properties ------------------------- - - You can specify the properties for the initial startup frame by -setting `initial-frame-plist' in your `.emacs' file. - - - Variable: initial-frame-plist - This variable's value is a plist of alternating property-value - pairs used when creating the initial X window frame. - - XEmacs creates the initial frame before it reads your `~/.emacs' - file. After reading that file, XEmacs checks - `initial-frame-plist', and applies the property settings in the - altered value to the already created initial frame. - - If these settings affect the frame geometry and appearance, you'll - see the frame appear with the wrong ones and then change to the - specified ones. If that bothers you, you can specify the same - geometry and appearance with X resources; those do take affect - before the frame is created. *Note X Resources: (xemacs)Resources - X. - - X resource settings typically apply to all frames. If you want to - specify some X resources solely for the sake of the initial frame, - and you don't want them to apply to subsequent frames, here's how - to achieve this: specify properties in `default-frame-plist' to - override the X resources for subsequent frames; then, to prevent - these from affecting the initial frame, specify the same - properties in `initial-frame-plist' with values that match the X - resources. - - If these properties specify a separate minibuffer-only frame via a -`minibuffer' property of `nil', and you have not yet created one, -XEmacs creates one for you. - - - Variable: minibuffer-frame-plist - This variable's value is a plist of properties used when creating - an initial minibuffer-only frame--if such a frame is needed, - according to the properties for the main initial frame. - - - Variable: default-frame-plist - This is a plist specifying default values of frame properties for - subsequent XEmacs frames (not the initial ones). - - See also `special-display-frame-plist', in *Note Choosing Window::. - - If you use options that specify window appearance when you invoke -XEmacs, they take effect by adding elements to `default-frame-plist'. -One exception is `-geometry', which adds the specified position to -`initial-frame-plist' instead. *Note Command Arguments: -(xemacs)Command Arguments. + `delete-windows-on' operates frame by frame. If a frame has + several windows showing different buffers, then those showing + BUFFER are removed, and the others expand to fill the space. If + all windows in some frame are showing BUFFER (including the case + where there is only one window), then the frame reverts to having a + single window showing another buffer chosen with `other-buffer'. + *Note The Buffer List::. - -File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties + The argument WHICH-FRAMES controls which frames to operate on: + + `nil' + Delete all windows showing BUFFER in any frame. + + `t' + Delete only windows showing BUFFER in the selected frame. + + `visible' + Delete all windows showing BUFFER in any visible frame. + + `0' + Delete all windows showing BUFFER in any visible frame. + + FRAME + If it is a frame, delete all windows showing BUFFER in that + frame. + + *Warning:* This is similar to, but not identical to, the meaning + of the WHICH-FRAMES argument to `next-window'; the meanings of + `nil' and `t' are reversed. -X Window Frame Properties -------------------------- + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is not `t'. - Just what properties a frame has depends on what display mechanism it -uses. Here is a table of the properties of an X window frame; of these, -`name', `height', `width', and `buffer-predicate' provide meaningful -information in non-X frames. + `nil' + Consider all devices on the selected console. -`name' - The name of the frame. Most window managers display the frame's - name in the frame's border, at the top of the frame. If you don't - specify a name, and you have more than one frame, XEmacs sets the - frame name based on the buffer displayed in the frame's selected + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + This function always returns `nil'. + + +File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows + +Selecting Windows +================= + + When a window is selected, the buffer in the window becomes the +current buffer, and the cursor will appear in it. + + - Function: selected-window &optional device + This function returns the selected window. This is the window in + which the cursor appears and to which many commands apply. Each + separate device can have its own selected window, which is + remembered as focus changes from device to device. Optional + argument DEVICE specifies which device to return the selected + window for, and defaults to the selected device. + + - Function: select-window window &optional norecord + This function makes WINDOW the selected window. The cursor then + appears in WINDOW (on redisplay). The buffer being displayed in + WINDOW is immediately designated the current buffer. + + If optional argument NORECORD is non-`nil' then the global and + per-frame buffer orderings are not modified, as by the function + `record-buffer'. + + The return value is WINDOW. + + (setq w (next-window)) + (select-window w) + => # + + - Special Form: save-selected-window forms... + This special form records the selected window, executes FORMS in + sequence, then restores the earlier selected window. It does not + save or restore anything about the sizes, arrangement or contents + of windows; therefore, if the FORMS change them, the changes are + permanent. + + The following functions choose one of the windows on the screen, +offering various criteria for the choice. + + - Function: get-lru-window &optional which-frames which-devices + This function returns the window least recently "used" (that is, + selected). The selected window is always the most recently used window. - If you specify the frame name explicitly when you create the - frame, the name is also used (instead of the name of the XEmacs - executable) when looking up X resources for the frame. - -`display' - The display on which to open this frame. It should be a string of - the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment - variable. - -`left' - The screen position of the left edge, in pixels, with respect to - the left edge of the screen. The value may be a positive number - POS, or a list of the form `(+ POS)' which permits specifying a - negative POS value. - - A negative number -POS, or a list of the form `(- POS)', actually - specifies the position of the right edge of the window with - respect to the right edge of the screen. A positive value of POS - counts toward the left. If the property is a negative integer - -POS then POS is positive! - -`top' - The screen position of the top edge, in pixels, with respect to the - top edge of the screen. The value may be a positive number POS, - or a list of the form `(+ POS)' which permits specifying a - negative POS value. - - A negative number -POS, or a list of the form `(- POS)', actually - specifies the position of the bottom edge of the window with - respect to the bottom edge of the screen. A positive value of POS - counts toward the top. If the property is a negative integer -POS - then POS is positive! - -`icon-left' - The screen position of the left edge _of the frame's icon_, in - pixels, counting from the left edge of the screen. This takes - effect if and when the frame is iconified. - -`icon-top' - The screen position of the top edge _of the frame's icon_, in - pixels, counting from the top edge of the screen. This takes - effect if and when the frame is iconified. - -`user-position' - Non-`nil' if the screen position of the frame was explicitly - requested by the user (for example, with the `-geometry' option). - Nothing automatically makes this property non-`nil'; it is up to - Lisp programs that call `make-frame' to specify this property as - well as specifying the `left' and `top' properties. - -`height' - The height of the frame contents, in characters. (To get the - height in pixels, call `frame-pixel-height'; see *Note Size and - Position::.) - -`width' - The width of the frame contents, in characters. (To get the - height in pixels, call `frame-pixel-width'; see *Note Size and - Position::.) - -`window-id' - The number of the X window for the frame. - -`minibuffer' - Whether this frame has its own minibuffer. The value `t' means - yes, `nil' means no, `only' means this frame is just a minibuffer. - If the value is a minibuffer window (in some other frame), the - new frame uses that minibuffer. (Minibuffer-only and - minibuffer-less frames are not yet implemented in XEmacs.) - -`buffer-predicate' - The buffer-predicate function for this frame. The function - `other-buffer' uses this predicate (from the selected frame) to - decide which buffers it should consider, if the predicate is not - `nil'. It calls the predicate with one arg, a buffer, once for - each buffer; if the predicate returns a non-`nil' value, it - considers that buffer. - -`scroll-bar-width' - The width of the vertical scroll bar, in pixels. - -`cursor-color' - The color for the cursor that shows point. - -`border-color' - The color for the border of the frame. - -`border-width' - The width in pixels of the window border. - -`internal-border-width' - The distance in pixels between text and border. - -`unsplittable' - If non-`nil', this frame's window is never split automatically. - -`inter-line-space' - The space in pixels between adjacent lines of text. (Not currently - implemented.) - -`modeline' - Whether the frame has a modeline. + 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. + + By default, only the windows in the selected frame are considered. + The optional argument WHICH-FRAMES changes this behavior. Here + are the possible values and their meanings: + + `nil' + Consider all the windows in the selected windows's frame, + plus the minibuffer used by that frame even if it lies in + some other frame. + + `t' + Consider all windows in all existing frames. + + `visible' + Consider all windows in all visible frames. (To get useful + results, you must ensure WINDOW is in a visible frame.) + + `0' + Consider all windows in all visible or iconified frames. + + FRAME + Consider all windows on frame FRAME. + + anything else + Consider precisely the windows in the selected window's + frame, and no others. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is non-`nil'. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + + - Function: get-largest-window &optional which-frames which-devices + This function returns the window with the largest area (height + times 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 that is first in the cyclic ordering of windows + (see following section), starting from the selected window. + + The remaining arguments control which set of windows are + considered. See `next-window', above.  -File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties - -Frame Size And Position ------------------------ - - You can read or change the size and position of a frame using the -frame properties `left', `top', `height', and `width'. Whatever -geometry properties you don't specify are chosen by the window manager -in its usual fashion. - - Here are some special features for working with sizes and positions: - - - Function: set-frame-position frame left top - This function sets the position of the top left corner of FRAME to - LEFT and TOP. These arguments are measured in pixels, and count - from the top left corner of the screen. Negative property values - count up or rightward from the top left corner of the screen. - - - Function: frame-height &optional frame - - Function: frame-width &optional frame - These functions return the height and width of FRAME, measured in - lines and columns. If you don't supply FRAME, they use the - selected frame. - - - Function: frame-pixel-height &optional frame - - Function: frame-pixel-width &optional frame - These functions return the height and width of FRAME, measured in - pixels. If you don't supply FRAME, they use the selected frame. - - - Function: set-frame-size frame cols rows &optional pretend - This function sets the size of FRAME, measured in characters; COLS - and ROWS specify the new width and height. (If PRETEND is - non-nil, it means that redisplay should act as if the frame's size - is COLS by ROWS, but the actual size of the frame should not be - changed. You should not normally use this option.) - - You can also use the functions `set-frame-height' and -`set-frame-width' to set the height and width individually. The frame -is the first argument and the size (in rows or columns) is the second. -(There is an optional third argument, PRETEND, which has the same -purpose as the corresponding argument in `set-frame-size'.) +File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows + +Cyclic Ordering of Windows +========================== + + When you use the command `C-x o' (`other-window') to select the next +window, it moves through all the windows on the screen in a specific +cyclic order. For any given configuration of windows, this order never +varies. It is called the "cyclic ordering of windows". + + This ordering generally goes from top to bottom, and from left to +right. But it may go down first or go right first, depending on the +order in which the windows were split. + + If the first split was vertical (into windows one above each other), +and then the subwindows were split horizontally, then the ordering is +left to right in the top of the frame, and then left to right in the +next lower part of the frame, and so on. If the first split was +horizontal, the ordering is top to bottom in the left part, and so on. +In general, within each set of siblings at any level in the window tree, +the order is left to right, or top to bottom. + + - Function: next-window &optional window minibuf which-frames + which-devices + This function returns the window following WINDOW in the cyclic + ordering of windows. This is the window that `C-x o' would select + if typed when WINDOW is selected. If WINDOW is the only window + visible, then this function returns WINDOW. If omitted, WINDOW + defaults to the selected window. + + The value of the argument MINIBUF determines whether the + minibuffer is included in the window order. Normally, when + MINIBUF is `nil', the minibuffer is included if it is currently + active; this is the behavior of `C-x o'. (The minibuffer window + is active while the minibuffer is in use. *Note Minibuffers::.) + + If MINIBUF is `t', then the cyclic ordering includes the + minibuffer window even if it is not active. + + If MINIBUF is neither `t' nor `nil', then the minibuffer window is + not included even if it is active. + + By default, only the windows in the selected frame are considered. + The optional argument WHICH-FRAMES changes this behavior. Here + are the possible values and their meanings: + + `nil' + Consider all the windows in WINDOW's frame, plus the + minibuffer used by that frame even if it lies in some other + frame. + + `t' + Consider all windows in all existing frames. + + `visible' + Consider all windows in all visible frames. (To get useful + results, you must ensure WINDOW is in a visible frame.) + + `0' + Consider all windows in all visible or iconified frames. + + FRAME + Consider all windows on frame FRAME. + + anything else + Consider precisely the windows in WINDOW's frame, and no + others. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is non-`nil'. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + If you use consistent values for MINIBUF, WHICH-FRAMES, and + WHICH-DEVICES, you can use `next-window' to iterate through the + entire cycle of acceptable windows, eventually ending up back at + the window you started with. `previous-window' traverses the same + cycle, in the reverse order. + + This example assumes there are two windows, both displaying the + buffer `windows.texi': + + (selected-window) + => # + (next-window (selected-window)) + => # + (next-window (next-window (selected-window))) + => # + + - Function: previous-window &optional window minibuf which-frames + which-devices + This function returns the window preceding WINDOW in the cyclic + ordering of windows. The other arguments specify which windows to + include in the cycle, as in `next-window'. + + - Command: other-window count &optional which-frames which-devices + This function selects the COUNTth following window in the cyclic + order. If COUNT is negative, then it selects the -COUNTth + preceding window. It returns `nil'. + + In an interactive call, COUNT is the numeric prefix argument. + + The other arguments specify which windows to include in the cycle, + as in `next-window'. + + - Function: walk-windows function &optional minibuf which-frames + which-devices + This function cycles through all windows, calling `function' once + for each window with the window as its sole argument. + + The other arguments specify which windows to cycle through, as in + `next-window'.  -File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties +File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows + +Buffers and Windows +=================== + + This section describes low-level functions to examine windows or to +display buffers in windows in a precisely controlled fashion. *Note +Displaying Buffers::, for related functions that find a window to use +and specify a buffer for it. The functions described there are easier +to use than these, but they employ heuristics in choosing or creating a +window; use these functions when you need complete control. + + - Function: set-window-buffer window buffer-or-name &optional norecord + This function makes WINDOW display BUFFER-OR-NAME as its contents. + BUFFER-OR-NAME can be a buffer or a buffer name. + + With non-`nil' optional argument NORECORD, do not modify the + global or per-frame buffer ordering. + + This function returns `nil'. + + (set-window-buffer (selected-window) "foo") + => nil -The Name of a Frame (As Opposed to Its Title) ---------------------------------------------- + - Function: window-buffer &optional window + This function returns the buffer that WINDOW is displaying. If + WINDOW is omitted, this function returns the buffer for the + selected window. - Under X, every frame has a name, which is not the same as the title -of the frame. A frame's name is used to look up its resources and does -not normally change over the lifetime of a frame. It is perfectly -allowable, and quite common, for multiple frames to have the same name. + (window-buffer) + => # - - Function: frame-name &optional frame - This function returns the name of FRAME, which defaults to the - selected frame if not specified. The name of a frame can also be - obtained from the frame's properties. *Note Frame Properties::. + - Function: get-buffer-window buffer-or-name &optional which-frames + which-devices + This function returns a window currently displaying + BUFFER-OR-NAME, or `nil' if there is none. If there are several + such windows, then the function returns the first one in the + cyclic ordering of windows, starting from the selected window. + *Note Cyclic Window Ordering::. - - Variable: default-frame-name - This variable holds the default name to assign to newly-created - frames. This can be overridden by arguments to `make-frame'. This - must be a string. + The remaining arguments control which windows to consider. They + have the same meaning as for `next-window'.  -File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames +File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows -Frame Titles -============ +Displaying Buffers in Windows +============================= - Every frame has a title; most window managers display the frame -title at the top of the frame. You can specify an explicit title with -the `name' frame property. But normally you don't specify this -explicitly, and XEmacs computes the title automatically. + In this section we describe convenient functions that choose a window +automatically and use it to display a specified buffer. These functions +can also split an existing window in certain circumstances. We also +describe variables that parameterize the heuristics used for choosing a +window. *Note Buffers and Windows::, for low-level functions that give +you more precise control. + + Do not use the functions in this section in order to make a buffer +current so that a Lisp program can access or modify it; they are too +drastic for that purpose, since they change the display of buffers in +windows, which is gratuitous and will surprise the user. Instead, use +`set-buffer' (*note Current Buffer::) and `save-excursion' (*note +Excursions::), which designate buffers as current for programmed access +without affecting the display of buffers in windows. + + - Command: switch-to-buffer buffer-or-name &optional norecord + This function makes BUFFER-OR-NAME the current buffer, and also + displays the buffer in the selected window. This means that a + human can see the buffer and subsequent keyboard commands will + apply to it. Contrast this with `set-buffer', which makes + BUFFER-OR-NAME the current buffer but does not display it in the + selected window. *Note Current Buffer::. + + If BUFFER-OR-NAME does not identify an existing buffer, then a new + buffer by that name is created. The major mode for the new buffer + is set according to the variable `default-major-mode'. *Note Auto + Major Mode::. + + Normally the specified buffer is put at the front of the buffer + list. This affects the operation of `other-buffer'. However, if + NORECORD is non-`nil', this is not done. *Note The Buffer List::. + + The `switch-to-buffer' function is often used interactively, as + the binding of `C-x b'. It is also used frequently in programs. + It always returns `nil'. + + - Command: switch-to-buffer-other-window buffer-or-name + This function makes BUFFER-OR-NAME the current buffer and displays + it in a window not currently selected. It then selects that + window. The handling of the buffer is the same as in + `switch-to-buffer'. + + 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. + + - Function: pop-to-buffer buffer-or-name &optional other-window + on-frame + This function makes BUFFER-OR-NAME the current buffer and switches + to it in some window, preferably not the window previously + selected. The "popped-to" window becomes the selected window + within its frame. + + If the variable `pop-up-frames' is non-`nil', `pop-to-buffer' + looks for a window in any visible frame already displaying the + buffer; if there is one, it returns that window and makes it be + selected within its frame. If there is none, it creates a new + frame and displays the buffer in it. + + If `pop-up-frames' is `nil', then `pop-to-buffer' operates + entirely within the selected frame. (If the selected frame has + just a minibuffer, `pop-to-buffer' operates within the most + recently selected frame that was not just a minibuffer.) + + If the variable `pop-up-windows' is non-`nil', windows may be + split to create a new window that is different from the original + window. For details, see *Note Choosing Window::. + + If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates + another window even if BUFFER-OR-NAME is already visible in the + selected window. Thus BUFFER-OR-NAME could end up displayed in + two windows. On the other hand, if BUFFER-OR-NAME is already + displayed in the selected window and OTHER-WINDOW is `nil', then + the selected window is considered sufficient display for + BUFFER-OR-NAME, so that nothing needs to be done. + + All the variables that affect `display-buffer' affect + `pop-to-buffer' as well. *Note Choosing Window::. + + If BUFFER-OR-NAME is a string that does not name an existing + buffer, a buffer by that name is created. The major mode for the + new buffer is set according to the variable `default-major-mode'. + *Note Auto Major Mode::. + + If ON-FRAME is non-`nil', it is the frame to pop to this buffer on. + + An example use of this function is found at the end of *Note + Filter Functions::. + + - Command: replace-buffer-in-windows buffer &optional which-frames + which-devices + This function replaces BUFFER with some other buffer in all + windows displaying it. The other buffer used is chosen with + `other-buffer'. In the usual applications of this function, you + don't care which other buffer is used; you just want to make sure + that BUFFER is no longer displayed. + + The optional arguments WHICH-FRAMES and WHICH-DEVICES have the + same meaning as with `delete-windows-on'. + + This function returns `nil'. - XEmacs computes the frame title based on a template stored in the -variable `frame-title-format'. + +File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows - - Variable: frame-title-format - This variable specifies how to compute a title for a frame when - you have not explicitly specified one. +Choosing a Window for Display +============================= - The variable's value is actually a modeline construct, just like - `modeline-format'. *Note Modeline Data::. + This section describes the basic facility that chooses a window to +display a buffer in--`display-buffer'. All the higher-level functions +and commands use this subroutine. Here we describe how to use +`display-buffer' and how to customize it. + + - Command: display-buffer buffer-or-name &optional not-this-window + override-frame + This command makes BUFFER-OR-NAME appear in some window, like + `pop-to-buffer', but it does not select that window and does not + make the buffer current. The identity of the selected window is + unaltered by this function. + + BUFFER-OR-NAME can be a buffer or the name of one. + + If NOT-THIS-WINDOW is non-`nil', it means to display the specified + buffer in a window other than the selected one, even if it is + already on display in the selected window. This can cause the + buffer to appear in two windows at once. Otherwise, if + BUFFER-OR-NAME is already being displayed in any window, that is + good enough, so this function does nothing. + + If OVERRIDE-FRAME is non-`nil', display on that frame instead of + the current frame (or the dedicated frame). + + `display-buffer' returns the window chosen to display + BUFFER-OR-NAME. + + Precisely how `display-buffer' finds or creates a window depends on + the variables described below. + + A window can be marked as "dedicated" to a particular buffer. Then +XEmacs will not automatically change which buffer appears in the +window, such as `display-buffer' might normally do. + + - Function: window-dedicated-p window + This function returns WINDOW's dedicated object, usually `t' or + `nil'. + + - Function: set-window-buffer-dedicated window buffer + This function makes WINDOW display BUFFER and be dedicated to that + buffer. Then XEmacs will not automatically change which buffer + appears in WINDOW. If BUFFER is `nil', this function makes WINDOW + not be dedicated (but doesn't change which buffer appears in it + currently). + + - User Option: pop-up-windows + This variable controls whether `display-buffer' makes new windows. + If it is non-`nil' and there is only one window, then that window + is split. If it is `nil', then `display-buffer' does not split + the single window, but uses it whole. + + - User Option: split-height-threshold + This variable determines when `display-buffer' may split a window, + if there are multiple windows. `display-buffer' always splits the + largest window if it has at least this many lines. If the largest + window is not this tall, it is split only if it is the sole window + and `pop-up-windows' is non-`nil'. + + - User Option: pop-up-frames + This variable controls whether `display-buffer' makes new frames. + If it is non-`nil', `display-buffer' looks for an existing window + already displaying the desired buffer, on any visible frame. If + it finds one, it returns that window. Otherwise it makes a new + frame. The variables `pop-up-windows' and + `split-height-threshold' do not matter if `pop-up-frames' is + non-`nil'. + + If `pop-up-frames' is `nil', then `display-buffer' either splits a + window or reuses one. + + *Note Frames::, for more information. + + - Variable: pop-up-frame-function + This variable specifies how to make a new frame if `pop-up-frames' + is non-`nil'. + + Its value should be a function of no arguments. When + `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 that creates a frame using properties from + `pop-up-frame-plist'. + + - Variable: pop-up-frame-plist + This variable holds a plist specifying frame properties used when + `display-buffer' makes a new frame. *Note Frame Properties::, for + more information about frame properties. + + - Variable: special-display-buffer-names + A list of buffer names for buffers that should be displayed + specially. If the buffer's name is in this list, `display-buffer' + handles the buffer specially. + + By default, special display means to give the buffer a dedicated + frame. - - Variable: frame-icon-title-format - This variable specifies how to compute the title for an iconified - frame, when you have not explicitly specified the frame title. - This title appears in the icon itself. + If an element is a list, instead of a string, then the CAR of the + list is the buffer name, and the rest of the list says how to + create the frame. There are two possibilities for the rest of the + list. It can be a plist, specifying frame properties, or it can + contain a function and arguments to give to it. (The function's + first argument is always the buffer to be displayed; the arguments + from the list come after that.) + + - Variable: special-display-regexps + A list of regular expressions that specify buffers that should be + displayed specially. If the buffer's name matches any of the + regular expressions in this list, `display-buffer' handles the + buffer specially. + + By default, special display means to give the buffer a dedicated + frame. - - Function: x-set-frame-icon-pixmap frame pixmap &optional mask - This function sets the icon of the given frame to the given image - instance, which should be an image instance object (as returned by - `make-image-instance'), a glyph object (as returned by - `make-glyph'), or `nil'. If a glyph object is given, the glyph - will be instantiated on the frame to produce an image instance - object. + If an element is a list, instead of a string, then the CAR of the + list is the regular expression, and the rest of the list says how + to create the frame. See above, under + `special-display-buffer-names'. + + - Variable: special-display-function + This variable holds the function to call to display a buffer + specially. It receives the buffer as an argument, and should + return the window in which it is displayed. + + The default value of this variable is + `special-display-popup-frame'. + + - Function: special-display-popup-frame buffer + This function makes BUFFER visible in a frame of its own. If + 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 BUFFER. + + This function uses an existing window displaying 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 BUFFER was created, then + presumably the window was previously made by this function. + + - User Option: special-display-frame-plist + This variable holds frame properties for + `special-display-popup-frame' to use when it creates a frame. + + - Variable: same-window-buffer-names + A list of buffer names for buffers that should be displayed in the + selected window. If the buffer's name is in this list, + `display-buffer' handles the buffer by switching to it in the + selected window. - If the given image instance has a mask, that will be used as the - icon mask; however, not all window managers support this. + - Variable: same-window-regexps + A list of regular expressions that specify buffers that should be + displayed in the selected window. If the buffer's name matches + any of the regular expressions in this list, `display-buffer' + handles the buffer by switching to it in the selected window. - The window manager is also not required to support color pixmaps, - only bitmaps (one plane deep). + - Variable: display-buffer-function + This variable is the most flexible way to customize the behavior of + `display-buffer'. If it is non-`nil', it should be a function + that `display-buffer' calls to do the work. The function should + accept two arguments, the same two arguments that `display-buffer' + received. It should choose or create a window, display the + specified buffer, and then return the window. - If the image instance does not have a mask, then the optional - third argument may be the image instance to use as the mask (it - must be one plane deep). *Note Glyphs::. + This hook takes precedence over all the other options and hooks + described above. + + A window can be marked as "dedicated" to its buffer. Then +`display-buffer' does not try to use that window. + + - Function: window-dedicated-p window + This function returns `t' if WINDOW is marked as dedicated; + otherwise `nil'. + + - Function: set-window-dedicated-p window flag + This function marks WINDOW as dedicated if FLAG is non-`nil', and + nondedicated otherwise.  -File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames +File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows -Deleting Frames -=============== +Windows and Point +================= - Frames remain potentially visible until you explicitly "delete" -them. A deleted frame cannot appear on the screen, but continues to -exist as a Lisp object until there are no references to it. + Each window has its own value of point, independent of the value of +point in other windows displaying the same buffer. This makes it useful +to have multiple windows showing one buffer. - - Command: delete-frame &optional frame - This function deletes the frame FRAME. By default, FRAME is the - selected frame. + * The window point is established when a window is first created; it + is initialized from the buffer's point, or from the window point + of another window opened on the buffer if such a window exists. - - Function: frame-live-p frame - The function `frame-live-p' returns non-`nil' if the frame FRAME - has not been deleted. + * Selecting a window sets the value of point in its buffer to the + window's value of point. Conversely, deselecting a window sets + the window's value of point from that of the buffer. Thus, when + you switch between windows that display a given buffer, the point + value for the selected window is in effect in the buffer, while + the point values for the other windows are stored in those windows. + + * As long as the selected window displays the current buffer, the + window's point and the buffer's point always move together; they + remain equal. + + * *Note Positions::, for more details on buffer positions. + + 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. + + - Function: window-point &optional window + This function returns the current position of point in WINDOW. + For a non-selected window, this is the value point would have (in + that window's buffer) if that window were selected. + + When WINDOW is the selected window and its buffer is also the + current buffer, the value returned is the same as the value of + point in that buffer. + + Strictly speaking, it would be more correct to return the + "top-level" value of point, outside of any `save-excursion' forms. + But that value is hard to find. + + - Function: set-window-point window position + This function positions point in WINDOW at position POSITION in + WINDOW's buffer.