-\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'.
-