Info Catalog elisp: Switching Buffers elisp: Windows elisp: Display Action Functions

elisp: Choosing Window

 
 27.13 Choosing a Window for Display
 ===================================
 
 The command ‘display-buffer’ flexibly chooses a window for display, and
 displays a specified buffer in that window.  It can be called
 interactively, via the key binding ‘C-x 4 C-o’.  It is also used as a
 subroutine by many functions and commands, including ‘switch-to-buffer’
 and ‘pop-to-buffer’ (Switching Buffers).
 
    This command performs several complex steps to find a window to
 display in.  These steps are described by means of “display actions”,
 which have the form ‘(FUNCTION . ALIST)’.  Here, FUNCTION is either a
 function or a list of functions, which we refer to as “action
 functions”; ALIST is an association list, which we refer to as an
 “action alist”.
 
    An action function accepts two arguments: the buffer to display and
 an action alist.  It attempts to display the buffer in some window,
 picking or creating a window according to its own criteria.  If
 successful, it returns the window; otherwise, it returns ‘nil’.  
 Display Action Functions, for a list of predefined action functions.
 
    ‘display-buffer’ works by combining display actions from several
 sources, and calling the action functions in turn, until one of them
 manages to display the buffer and returns a non-‘nil’ value.
 
  -- Command: display-buffer buffer-or-name &optional action frame
      This command makes BUFFER-OR-NAME appear in some window, without
      selecting the window or making the buffer current.  The argument
      BUFFER-OR-NAME must be a buffer or the name of an existing buffer.
      The return value is the window chosen to display the buffer.
 
      The optional argument ACTION, if non-‘nil’, should normally be a
      display action (described above).  ‘display-buffer’ builds a list
      of action functions and an action alist, by consolidating display
      actions from the following sources (in order):
 
         • The variable ‘display-buffer-overriding-action’.
 
         • The user option ‘display-buffer-alist’.
 
         • The ACTION argument.
 
         • The user option ‘display-buffer-base-action’.
 
         • The constant ‘display-buffer-fallback-action’.
 
      Each action function is called in turn, passing the buffer as the
      first argument and the combined action alist as the second
      argument, until one of the functions returns non-‘nil’.  The caller
      can pass ‘(allow-no-window . t)’ as an element of the action alist
      to indicate its readiness to handle the case of not displaying the
      buffer in a window.
 
      The argument ACTION can also have a non-‘nil’, non-list value.
      This has the special meaning that the buffer should be displayed in
      a window other than the selected one, even if the selected window
      is already displaying it.  If called interactively with a prefix
      argument, ACTION is ‘t’.
 
      The optional argument FRAME, if non-‘nil’, specifies which frames
      to check when deciding whether the buffer is already displayed.  It
      is equivalent to adding an element ‘(reusable-frames . FRAME)’ to
      the action alist of ACTION.  Display Action Functions.
 
  -- Variable: display-buffer-overriding-action
      The value of this variable should be a display action, which is
      treated with the highest priority by ‘display-buffer’.  The default
      value is empty, i.e., ‘(nil . nil)’.
 
  -- User Option: display-buffer-alist
      The value of this option is an alist mapping conditions to display
      actions.  Each condition may be either a regular expression
      matching a buffer name or a function that takes two arguments: a
      buffer name and the ACTION argument passed to ‘display-buffer’.  If
      the name of the buffer passed to ‘display-buffer’ either matches a
      regular expression in this alist or the function specified by a
      condition returns non-‘nil’, then ‘display-buffer’ uses the
      corresponding display action to display the buffer.
 
  -- User Option: display-buffer-base-action
      The value of this option should be a display action.  This option
      can be used to define a standard display action for calls to
      ‘display-buffer’.
 
  -- Constant: display-buffer-fallback-action
      This display action specifies the fallback behavior for
      ‘display-buffer’ if no other display actions are given.
 

Info Catalog elisp: Switching Buffers elisp: Windows elisp: Display Action Functions