-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-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")
+ => #<buffer 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 `<N>' 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")
+ => #<buffer bar>
+ (generate-new-buffer "bar")
+ => #<buffer bar<2>>
+ (generate-new-buffer "bar")
+ => #<buffer bar<3>>
- - 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::.
\1f
-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::.
\1f
-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
+================
-\1f
-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".
-\1f
-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 on "windows.texi" 0x679b>
- (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 on "windows.texi" 0x7538>
- (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 on "windows.texi" 0x68a6>
- (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 on "windows.texi" 0x7538>
- (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.
-\1f
-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.
-\1f
-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")
+ => #<buffer "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"))
+ => #<buffer "*scratch*">
- 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*"))
+ => (#<buffer "indirect">)
\1f
-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)
- => #<window 25 on control.texi>
- (setq w (selected-window))
- => #<window 19 on control.texi>
- (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.
\1f
-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.
\1f
-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 8 on windows.texi>
+ (window-edges) ; Edges in order:
+ => (0 0 80 50) ; left-top-right-bottom
+
+ ;; Returns window created
+ (setq w2 (split-window w 15))
+ => #<window 28 on windows.texi>
+ (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 32 on windows.texi>
+ (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))
\1f
-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.
-\1f
-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.
-\1f
-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::.
-\1f
-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'.
+
+\1f
+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)
+ => #<window 65 on windows.texi>
+
+ - 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.
\1f
-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)
+ => #<window 56 on windows.texi>
+ (next-window (selected-window))
+ => #<window 52 on windows.texi>
+ (next-window (next-window (selected-window)))
+ => #<window 56 on windows.texi>
+
+ - 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'.
\1f
-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
-The Name of a Frame (As Opposed to Its Title)
----------------------------------------------
+Buffers and Windows
+===================
- 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.
+ 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
+
+ - 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.
- - 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::.
+ (window-buffer)
+ => #<buffer windows.texi>
- - 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.
+ - 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::.
+
+ The remaining arguments control which windows to consider. They
+ have the same meaning as for `next-window'.
+
+\1f
+File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
+
+Displaying Buffers in Windows
+=============================
+
+ 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'.
\1f
-File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
+File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
-Frame Titles
-============
+Choosing a Window for Display
+=============================
- 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.
+ 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.
- XEmacs computes the frame title based on a template stored in the
-variable `frame-title-format'.
+ 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.
- - Variable: frame-title-format
- This variable specifies how to compute a title for a frame when
- you have not explicitly specified one.
+ 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.
- The variable's value is actually a modeline construct, just like
- `modeline-format'. *Note Modeline Data::.
+ - 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.
- - 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.
+ - 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.
- - 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.
+ This hook takes precedence over all the other options and hooks
+ described above.
- If the given image instance has a mask, that will be used as the
- icon mask; however, not all window managers support this.
+ A window can be marked as "dedicated" to its buffer. Then
+`display-buffer' does not try to use that window.
- The window manager is also not required to support color pixmaps,
- only bitmaps (one plane deep).
+ - Function: window-dedicated-p window
+ This function returns `t' if WINDOW is marked as dedicated;
+ otherwise `nil'.
- 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::.
+ - Function: set-window-dedicated-p window flag
+ This function marks WINDOW as dedicated if FLAG is non-`nil', and
+ nondedicated otherwise.
\1f
-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
+=================
+
+ 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.
+
+ * 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.
+
+ * 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.
- 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.
+ 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.
- - Command: delete-frame &optional FRAME
- This function deletes the frame FRAME. By default, FRAME is the
- selected frame.
+ 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: frame-live-p FRAME
- The function `frame-live-p' returns non-`nil' if the frame FRAME
- has not been deleted.
+ - Function: set-window-point window position
+ This function positions point in WINDOW at position POSITION in
+ WINDOW's buffer.
projects / chise / xemacs-chise.git- / blobdiff