X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-25;fp=info%2Flispref.info-25;h=0000000000000000000000000000000000000000;hb=a5812bf2ff9a9cf40f4ff78dcb83f5b4c295bd18;hp=42513cfebd2040cfb59e10f5a27e2af0c812a4bf;hpb=ccce6217f84987dff10ed3d2b60b9f0f65d8f25a;p=chise%2Fxemacs-chise.git.1 diff --git a/info/lispref.info-25 b/info/lispref.info-25 deleted file mode 100644 index 42513cf..0000000 --- a/info/lispref.info-25 +++ /dev/null @@ -1,1219 +0,0 @@ -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. - - -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) - => (# - # # - # #) - - ;; 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::. - - -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") - => # - - 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 `' 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") - => # - (generate-new-buffer "bar") - => #> - (generate-new-buffer "bar") - => #> - - The major mode for the new buffer is set to Fundamental mode. The - variable `default-major-mode' is handled at a higher level. *Note - Auto Major Mode::. - - See the related function `generate-new-buffer-name' in *Note - Buffer Names::. - - -File: lispref.info, Node: 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::. - - -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") - => # - - - 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")) - => # - - - Function: buffer-indirect-children &optional BUFFER - This function returns a list of all indirect buffers whose base - buffer is BUFFER. If BUFFER is indirect, the return value will - always be nil; see `make-indirect-buffer'. If BUFFER is not - supplied, it defaults to the current buffer. - - (buffer-indirect-children (get-buffer "*scratch*")) - => (#) - - -File: lispref.info, Node: 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. - - -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. - - -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-edges) ; Edges in order: - => (0 0 80 50) ; left-top-right-bottom - - ;; Returns window created - (setq w2 (split-window w 15)) - => # - - (window-edges w2) - => (0 15 80 50) ; Bottom window; - ; top is line 15 - - (window-edges w) - => (0 0 80 15) ; Top window - - The frame looks like this: - - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Next, the top window is split horizontally: - - (setq w3 (split-window w 35 t)) - => # - - (window-edges w3) - => (35 0 80 15) ; Left edge at column 35 - - (window-edges w) - => (0 0 35 15) ; Right edge at column 35 - - (window-edges w2) - => (0 15 80 50) ; Bottom window unchanged - - Now, the screen looks like this: - - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Normally, Emacs indicates the border between two side-by-side - windows with a scroll bar (*note Scroll Bars: X Frame Properties.) - or `|' characters. The display table can specify alternative - border characters; see *Note Display Tables::. - - - Command: split-window-vertically &optional SIZE - This function splits the selected window into two windows, one - above the other, leaving the selected window with SIZE lines. - - This function is simply an interface to `split-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. - - -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'. - - -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) - => # - - - 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. - - -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) - => # - (next-window (selected-window)) - => # - (next-window (next-window (selected-window))) - => # - - - 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. - - -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) - => # - - - 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. - - -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'. - - -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. -