+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
-
-The Buffer List
-===============
-
- The "buffer list" is a list of all live buffers. Creating a buffer
-adds it to this list, and killing a buffer deletes it. The order of
-the buffers in the list is based primarily on how recently each buffer
-has been displayed in the selected window. Buffers move to the front
-of the list when they are selected and to the end when they are buried.
-Several functions, notably `other-buffer', use this ordering. A
-buffer list displayed for the user also follows this order.
-
- Every frame has its own order for the buffer list. Switching to a
-new buffer inside of a particular frame changes the buffer list order
-for that frame, but does not affect the buffer list order of any other
-frames. In addition, there is a global, non-frame buffer list order
-that is independent of the buffer list orders for any particular frame.
-
- Note that the different buffer lists all contain the same elements.
-It is only the order of those elements that is different.
-
- - Function: buffer-list &optional FRAME
- This function returns a list of all buffers, including those whose
- names begin with a space. The elements are actual buffers, not
- their names. The order of the list is specific to FRAME, which
- defaults to the current frame. If FRAME is `t', the global,
- non-frame ordering is returned instead.
-
- (buffer-list)
- => (#<buffer buffers.texi>
- #<buffer *Minibuf-1*> #<buffer buffer.c>
- #<buffer *Help*> #<buffer TAGS>)
-
- ;; Note that the name of the minibuffer
- ;; begins with a space!
- (mapcar (function buffer-name) (buffer-list))
- => ("buffers.texi" " *Minibuf-1*"
- "buffer.c" "*Help*" "TAGS")
-
- Buffers appear earlier in the list if they were current more
- recently.
-
- This list is a copy of a list used inside XEmacs; modifying it has
- no effect on the buffers.
-
- - Function: other-buffer &optional BUFFER-OR-NAME FRAME VISIBLE-OK
- This function returns the first buffer in the buffer list other
- than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
- (FRAME defaults to the current frame. If FRAME is `t', then the
- global, non-frame ordering is used.) Usually this is the buffer
- most recently shown in the selected window, aside from
- BUFFER-OR-NAME. Buffers are moved to the front of the list when
- they are selected and to the end when they are buried. Buffers
- whose names start with a space are not considered.
-
- If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
- `other-buffer' returns the first buffer on the buffer list that is
- not visible in any window in a visible frame.
-
- If the selected frame has a non-`nil' `buffer-predicate' property,
- then `other-buffer' uses that predicate to decide which buffers to
- consider. It calls the predicate once for each buffer, and if the
- value is `nil', that buffer is ignored. *Note X Frame
- Properties::.
-
- If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
- visible in any window on any visible frame, except as a last
- resort. If VISIBLE-OK is non-`nil', then it does not matter
- whether a buffer is displayed somewhere or not.
-
- If no suitable buffer exists, the buffer `*scratch*' is returned
- (and created, if necessary).
-
- Note that in FSF Emacs 19, there is no FRAME argument, and
- VISIBLE-OK is the second argument instead of the third. FSF Emacs
- 19.
-
- - Command: list-buffers &optional FILES-ONLY
- This function displays a listing of the names of existing buffers.
- It clears the buffer `*Buffer List*', then inserts the listing
- into that buffer and displays it in a window. `list-buffers' is
- intended for interactive use, and is described fully in `The XEmacs
- Reference Manual'. It returns `nil'.
-
- - Command: bury-buffer &optional BUFFER-OR-NAME
- This function puts BUFFER-OR-NAME at the end of the buffer list
- without changing the order of any of the other buffers on the list.
- This buffer therefore becomes the least desirable candidate for
- `other-buffer' to return.
-
- If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
- current buffer. In addition, if the buffer is displayed in the
- selected window, this switches to some other buffer (obtained using
- `other-buffer') in the selected window. But if the buffer is
- displayed in some other window, it remains displayed there.
-
- If you wish to replace a buffer in all the windows that display
- it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
-
-\1f
-File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
-
-Creating Buffers
-================
-
- 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.
-
- 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::.).
-
- - 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.
-
- An error is signaled if NAME is not a string.
-
- (get-buffer-create "foo")
- => #<buffer foo>
-
- 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: 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.
-
- An error is signaled if NAME is not a string.
-
- (generate-new-buffer "bar")
- => #<buffer bar>
- (generate-new-buffer "bar")
- => #<buffer bar<2>>
- (generate-new-buffer "bar")
- => #<buffer bar<3>>
-
- 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: 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 BUFFER
- This function returns `nil' if BUFFER is deleted, and `t'
- 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'.
-
- 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")
-
- ---------- Buffer: Minibuffer ----------
- Buffer foo.changed modified; kill anyway? (yes or no) yes
- ---------- Buffer: Minibuffer ----------
-
- => 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: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
-
-Indirect Buffers
-================
-
- 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".
-
- 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.
-
- 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.
-
- 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.
-
- Killing an indirect buffer has no effect on its base buffer. Killing
-the base buffer kills all its indirect children.
-
- - 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.
-
- If BASE-BUFFER is an indirect buffer, its base buffer is used as
- the base for the new buffer.
-
- (make-indirect-buffer "*scratch*" "indirect")
- => #<buffer "indirect">
-
- - 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*">
-
- - 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: Windows, Next: Frames, Prev: Buffers, Up: Top
-
-Windows
-*******
-
- 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: Basic Windows, Next: Splitting Windows, Up: Windows
-
-Basic Concepts of Emacs 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.
-
- 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.
-
- 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::.
-
- 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::.)
-
- 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
-
- * 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: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
-
-Splitting Windows
-=================
-
- 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 NO-MINI ALL-FRAMES
- This function returns non-`nil' if there is only one window. The
- argument NO-MINI, 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 argument ALL-FRAME controls which set of windows are counted.
- * If it is `nil' or omitted, then count only the selected
- frame, plus the minibuffer it uses (which may be on another
- frame).
-
- * If it is `t', then windows on all frames that currently exist
- (including invisible and iconified frames) are counted.
-
- * If it is the symbol `visible', then windows on all visible
- frames are counted.
-
- * If it is the number 0, then windows on all visible and
- iconified frames are counted.
-
- * If it is any other value, then precisely the windows in
- WINDOW's frame are counted, excluding the minibuffer in use
- if it lies in some other frame.
-
- - 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-windows'. 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-windows'. 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))
-
- - Function: one-window-p &optional NO-MINI ALL-FRAMES
- This function returns non-`nil' if there is only one window. The
- argument NO-MINI, 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 argument ALL-FRAMES specifies which frames to consider. Here
- are the possible values and their meanings:
-
- `nil'
- Count the windows in the selected frame, plus the minibuffer
- used by that frame even if it lies in some other frame.
-
- `t'
- Count all windows in all existing frames.
-
- `visible'
- Count all windows in all visible frames.
-
- 0
- Count all windows in all visible or iconified frames.
-
- anything else
- Count precisely the windows in the selected frame, and no
- others.
-
-\1f
-File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
-
-Deleting Windows
-================
-
- 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.
-
- 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.)
-
- - Function: window-live-p WINDOW
- This function returns `nil' if WINDOW is deleted, and `t'
- otherwise.
-
- *Warning:* Erroneous information or fatal errors may result from
- using a deleted window as if it were live.
-
- - Command: delete-window &optional WINDOW
- This function removes WINDOW from the display. If WINDOW is
- omitted, then the selected window is deleted. An error is signaled
- if there is only one window when `delete-window' is called.
-
- This function returns `nil'.
-
- When `delete-window' is called interactively, WINDOW defaults to
- the selected window.
-
- - 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.
-
- The result is `nil'.
-
- - Command: delete-windows-on BUFFER &optional FRAME
- This function deletes all windows showing BUFFER. If there are no
- windows showing BUFFER, it does nothing.
-
- `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::.
-
- The argument FRAME controls which frames to operate on:
-
- * If it is `nil', operate on the selected frame.
-
- * If it is `t', operate on all frames.
-
- * If it is `visible', operate on all visible frames.
-
- * 0 If it is 0, operate on all visible or iconified frames.
-
- * If it is a frame, operate on that frame.
-
- 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>
-
- - Macro: save-selected-window FORMS...
- This macro 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 FRAME
- This function returns the window least recently "used" (that is,
- selected). The selected window is always the most recently used
- window.
-
- The selected window can be the least recently used window if it is
- the only window. A newly created window becomes the least
- recently used window until it is selected. A minibuffer window is
- never a candidate.
-
- The argument FRAME controls which windows are considered.
-
- * If it is `nil', consider windows on the selected frame.
-
- * If it is `t', consider windows on all frames.
-
- * If it is `visible', consider windows on all visible frames.
-
- * If it is 0, consider windows on all visible or iconified
- frames.
-
- * If it is a frame, consider windows on that frame.
-
- - Function: get-largest-window &optional FRAME
- 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 argument FRAME controls which set of windows are considered.
- See `get-lru-window', above.
-
-\1f
-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 ALL-FRAMES
- 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.
-
- The argument ALL-FRAMES specifies which frames to consider. 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.
-
- anything else
- Consider precisely the windows in WINDOW's frame, and no
- others.
-
- 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 ALL-FRAMES
- 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 FRAME
- 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 argument FRAME controls which set of windows are considered.
- * If it is `nil' or omitted, then windows on the selected frame
- are considered.
-
- * If it is a frame, then windows on that frame are considered.
-
- * If it is `t', then windows on all frames that currently exist
- (including invisible and iconified frames) are considered.
-
- * If it is the symbol `visible', then windows on all visible
- frames are considered.
-
- * If it is the number 0, then windows on all visible and
- iconified frames are considered.
-
- * If it is any other value, then the behavior is undefined.
-
- - Function: walk-windows PROC &optional MINIBUF ALL-FRAMES
- This function cycles through all windows, calling `proc' once for
- each window with the window as its sole argument.
-
- The optional arguments MINIBUF and ALL-FRAMES specify the set of
- windows to include in the scan. See `next-window', above, for
- details.
-
-\1f
-File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
-
-Buffers and Windows
-===================
-
- This section describes low-level functions to examine windows or to
-display buffers in windows in a precisely controlled fashion. *Note
-Displaying Buffers::, for related functions that find a window to use
-and specify a buffer for it. The functions described there are easier
-to use than these, but they employ heuristics in choosing or creating a
-window; use these functions when you need complete control.
-
- - Function: set-window-buffer WINDOW BUFFER-OR-NAME
- This function makes WINDOW display BUFFER-OR-NAME as its contents.
- It 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.
-
- (window-buffer)
- => #<buffer windows.texi>
-
- - Function: get-buffer-window BUFFER-OR-NAME &optional FRAME
- 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 argument ALL-FRAMES controls which windows to consider.
-
- * If it is `nil', consider windows on the selected frame.
-
- * If it is `t', consider windows on all frames.
-
- * If it is `visible', consider windows on all visible frames.
-
- * If it is 0, consider windows on all visible or iconified
- frames.
-
- * If it is a frame, consider windows on that frame.
-
-\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
- 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.
-
- This function returns `nil'.
-
-\1f
-File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
-
-Choosing a Window for Display
-=============================
-
- 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
- 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.
-
- 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.
-
- `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.
-
- 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.
-
- 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.
-
- - 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: 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.
-
- This hook takes precedence over all the other options and hooks
- described above.
-
- A window can be marked as "dedicated" to its buffer. Then
-`display-buffer' does not try to use that window.
-
- - Function: window-dedicated-p WINDOW
- This function returns `t' if WINDOW is marked as dedicated;
- otherwise `nil'.
-
- - Function: set-window-dedicated-p WINDOW FLAG
- This function marks WINDOW as dedicated if FLAG is non-`nil', and
- nondedicated otherwise.
-
projects / chise / xemacs-chise.git.1 / blobdiff