+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 object
+ This function returns `t' if OBJECT is an editor buffer that has
+ not been deleted, `nil' otherwise.
+
+ - Command: kill-buffer buffer-or-name
+ This function kills the buffer BUFFER-OR-NAME, freeing all its
+ memory for use as space for other buffers. (Emacs version 18 and
+ older was unable to return the memory to the operating system.)
+ It returns `nil'. The argument BUFFER-OR-NAME may be a buffer or
+ the name of one.
+
+ Any processes that have this buffer as the `process-buffer' are
+ sent the `SIGHUP' signal, which normally causes them to terminate.
+ (The basic meaning of `SIGHUP' is that a dialup line has been
+ disconnected.) *Note Deleting Processes::.
+
+ If the buffer is visiting a file and contains unsaved changes,
+ `kill-buffer' asks the user to confirm before the buffer is killed.
+ It does this even if not called interactively. To prevent the
+ request for confirmation, clear the modified flag before calling
+ `kill-buffer'. *Note Buffer Modification::.
+
+ Killing a buffer that is already dead has no effect.
+
+ (kill-buffer "foo.unchanged")
+ => nil
+ (kill-buffer "foo.changed")
+
+ ---------- 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 nomini which-frames which-devices
+ This function returns non-`nil' if there is only one window. The
+ argument NOMINI, if non-`nil', means don't count the minibuffer
+ even if it is active; otherwise, the minibuffer window is
+ included, if active, in the total number of windows which is
+ compared against one.
+
+ The remaining arguments controls which set of windows are counted,
+ as with `next-window'.
+
+ - Command: split-window &optional window size horizontal
+ This function splits WINDOW into two windows. The original window
+ WINDOW remains the selected window, but occupies only part of its
+ former screen area. The rest is occupied by a newly created
+ window which is returned as the value of this function.
+
+ If HORIZONTAL is non-`nil', then WINDOW splits into two side by
+ side windows. The original window WINDOW keeps the leftmost SIZE
+ columns, and gives the rest of the columns to the new window.
+ Otherwise, it splits into windows one above the other, and WINDOW
+ keeps the upper SIZE lines and gives the rest of the lines to the
+ new window. The original window is therefore the left-hand or
+ upper of the two, and the new window is the right-hand or lower.
+
+ If WINDOW is omitted or `nil', then the selected window is split.
+ If SIZE is omitted or `nil', then WINDOW is divided evenly into
+ two parts. (If there is an odd line, it is allocated to the new
+ window.) When `split-window' is called interactively, all its
+ arguments are `nil'.
+
+ The following example starts with one window on a frame that is 50
+ lines high by 80 columns wide; then the window is split.
+
+ (setq w (selected-window))
+ => #<window 8 on windows.texi>
+ (window-edges) ; Edges in order:
+ => (0 0 80 50) ; left-top-right-bottom
+
+ ;; Returns window created
+ (setq w2 (split-window w 15))
+ => #<window 28 on windows.texi>
+ (window-edges w2)
+ => (0 15 80 50) ; Bottom window;
+ ; top is line 15
+ (window-edges w)
+ => (0 0 80 15) ; Top window
+
+ The frame looks like this:
+
+ __________
+ | | line 0
+ | w |
+ |__________|
+ | | line 15
+ | w2 |
+ |__________|
+ line 50
+ column 0 column 80
+
+ Next, the top window is split horizontally:
+
+ (setq w3 (split-window w 35 t))
+ => #<window 32 on windows.texi>
+ (window-edges w3)
+ => (35 0 80 15) ; Left edge at column 35
+ (window-edges w)
+ => (0 0 35 15) ; Right edge at column 35
+ (window-edges w2)
+ => (0 15 80 50) ; Bottom window unchanged
+
+ Now, the screen looks like this:
+
+ column 35
+ __________
+ | | | line 0
+ | w | w3 |
+ |___|______|
+ | | line 15
+ | w2 |
+ |__________|
+ line 50
+ column 0 column 80
+
+ Normally, Emacs indicates the border between two side-by-side
+ windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
+ or `|' characters. The display table can specify alternative
+ border characters; see *Note Display Tables::.
+
+ - Command: split-window-vertically &optional size
+ This function splits the selected window into two windows, one
+ above the other, leaving the selected window with SIZE lines.
+
+ This function is simply an interface to `split-window'. Here is
+ the complete function definition for it:
+
+ (defun split-window-vertically (&optional arg)
+ "Split current window into two windows, one above the other."
+ (interactive "P")
+ (split-window nil (and arg (prefix-numeric-value arg))))
+
+ - Command: split-window-horizontally &optional size
+ This function splits the selected window into two windows
+ side-by-side, leaving the selected window with SIZE columns.
+
+ This function is simply an interface to `split-window'. Here is
+ the complete definition for `split-window-horizontally' (except for
+ part of the documentation string):
+
+ (defun split-window-horizontally (&optional arg)
+ "Split selected window into two windows, side by side..."
+ (interactive "P")
+ (split-window nil (and arg (prefix-numeric-value arg)) t))
+
+\1f
+File: lispref.info, Node: 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 force
+ This function removes WINDOW from the display. If WINDOW is
+ omitted, then the selected window is deleted. If window is the
+ only one on its frame, the frame is deleted as well.
+
+ Normally, you cannot delete the last non-minibuffer-only frame
+ (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
+ is signaled instead. However, if optional second argument FORCE is
+ non-`nil', you can delete the last frame. (This will automatically
+ call `save-buffers-kill-emacs'.)
+
+ This function returns `nil'.
+
+ When `delete-window' is called interactively, the selected window
+ is deleted.
+
+ - 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 which-frames
+ which-devices
+ 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 WHICH-FRAMES controls which frames to operate on:
+
+ `nil'
+ Delete all windows showing BUFFER in any frame.
+
+ `t'
+ Delete only windows showing BUFFER in the selected frame.
+
+ `visible'
+ Delete all windows showing BUFFER in any visible frame.
+
+ `0'
+ Delete all windows showing BUFFER in any visible frame.
+
+ FRAME
+ If it is a frame, delete all windows showing BUFFER in that
+ frame.
+
+ *Warning:* This is similar to, but not identical to, the meaning
+ of the WHICH-FRAMES argument to `next-window'; the meanings of
+ `nil' and `t' are reversed.
+
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES. This
+ value is only meaningful if WHICH-FRAMES is not `t'.
+
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ This function always returns `nil'.
+
+\1f