Info Catalog elisp: Cyclic Window Ordering elisp: Windows elisp: Switching Buffers

elisp: Buffers and Windows

 
 27.11 Buffers and Windows
 =========================
 
 This section describes low-level functions for examining and setting the
 contents of windows.  Switching Buffers, for higher-level
 functions for displaying a specific buffer in a window.
 
  -- Function: window-buffer &optional window
      This function returns the buffer that WINDOW is displaying.  If
      WINDOW is omitted or ‘nil’ it defaults to the selected window.  If
      WINDOW is an internal window, this function returns ‘nil’.
 
  -- Function: set-window-buffer window buffer-or-name &optional
           keep-margins
      This function makes WINDOW display BUFFER-OR-NAME.  WINDOW should
      be a live window; if ‘nil’, it defaults to the selected window.
      BUFFER-OR-NAME should be a buffer, or the name of an existing
      buffer.  This function does not change which window is selected,
      nor does it directly change which buffer is current (Current
      Buffer).  Its return value is ‘nil’.
 
      If WINDOW is “strongly dedicated” to a buffer and BUFFER-OR-NAME
      does not specify that buffer, this function signals an error.
      Dedicated Windows.
 
      By default, this function resets WINDOW’s position, display
      margins, fringe widths, and scroll bar settings, based on the local
      variables in the specified buffer.  However, if the optional
      argument KEEP-MARGINS is non-‘nil’, it leaves the display margins
      and fringe widths unchanged.
 
      When writing an application, you should normally use the
      higher-level functions described in Switching Buffers,
      instead of calling ‘set-window-buffer’ directly.
 
      This runs ‘window-scroll-functions’, followed by
      ‘window-configuration-change-hook’.  Window Hooks.
 
  -- Variable: buffer-display-count
      This buffer-local variable records the number of times a buffer has
      been displayed in a window.  It is incremented each time
      ‘set-window-buffer’ is called for the buffer.
 
  -- Variable: buffer-display-time
      This buffer-local variable records the time at which a buffer was
      last displayed in a window.  The value is ‘nil’ if the buffer has
      never been displayed.  It is updated each time ‘set-window-buffer’
      is called for the buffer, with the value returned by ‘current-time’
      (Time of Day).
 
  -- Function: get-buffer-window &optional buffer-or-name all-frames
      This function returns the first window displaying BUFFER-OR-NAME in
      the cyclic ordering of windows, starting from the selected window
      (Cyclic Window Ordering).  If no such window exists, the
      return value is ‘nil’.
 
      BUFFER-OR-NAME should be a buffer or the name of a buffer; if
      omitted or ‘nil’, it defaults to the current buffer.  The optional
      argument ALL-FRAMES specifies which windows to consider:
 
         • ‘t’ means consider windows on all existing frames.
         • ‘visible’ means consider windows on all visible frames.
         • 0 means consider windows on all visible or iconified frames.
         • A frame means consider windows on that frame only.
         • Any other value means consider windows on the selected frame.
 
      Note that these meanings differ slightly from those of the
      ALL-FRAMES argument to ‘next-window’ (Cyclic Window
      Ordering).  This function may be changed in a future version of
      Emacs to eliminate this discrepancy.
 
  -- Function: get-buffer-window-list &optional buffer-or-name minibuf
           all-frames
      This function returns a list of all windows currently displaying
      BUFFER-OR-NAME.  BUFFER-OR-NAME should be a buffer or the name of
      an existing buffer.  If omitted or ‘nil’, it defaults to the
      current buffer.  If the currently selected window displays
      BUFFER-OR-NAME, it will be the first in the list returned by this
      function.
 
      The arguments MINIBUF and ALL-FRAMES have the same meanings as in
      the function ‘next-window’ (Cyclic Window Ordering).  Note
      that the ALL-FRAMES argument does _not_ behave exactly like in
      ‘get-buffer-window’.
 
  -- Command: replace-buffer-in-windows &optional buffer-or-name
      This command replaces BUFFER-OR-NAME with some other buffer, in all
      windows displaying it.  BUFFER-OR-NAME should be a buffer, or the
      name of an existing buffer; if omitted or ‘nil’, it defaults to the
      current buffer.
 
      The replacement buffer in each window is chosen via
      ‘switch-to-prev-buffer’ (Window History).  Any dedicated
      window displaying BUFFER-OR-NAME is deleted if possible (
      Dedicated Windows).  If such a window is the only window on its
      frame and there are other frames on the same terminal, the frame is
      deleted as well.  If the dedicated window is the only window on the
      only frame on its terminal, the buffer is replaced anyway.
 

Info Catalog elisp: Cyclic Window Ordering elisp: Windows elisp: Switching Buffers