GNU Info

(elisp)Displaying Buffers

---

Next: Choosing Window Prev: Buffers and Windows Up: Windows

---

Enter node , (file) or (file)node

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.  All of these functions work by calling
`set-window-buffer'.

   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 would be gratuitous and surprise the user.  Instead, use
`set-buffer' and `save-current-buffer' (Note: Current Buffer), 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 (both the selected frame's buffer list and the
     frame-independent 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 &optional
          norecord
     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.

     This function updates the buffer list just like `switch-to-buffer'
     unless NORECORD is non-`nil'.

 - Function: pop-to-buffer buffer-or-name &optional other-window
          norecord
     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.

     This function updates the buffer list just like `switch-to-buffer'
     unless NORECORD is non-`nil'.

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