Function: display-buffer-override-next-command

display-buffer-override-next-command is a byte-compiled function defined in window.el.gz.

Signature

(display-buffer-override-next-command PRE-FUNCTION &optional POST-FUNCTION ECHO)

Documentation

Set display-buffer-overriding-action for the next command.

pre-function is called to prepare the window where the buffer should be displayed. This function takes two arguments buffer and alist, and should return a cons with the displayed window and its type. See the meaning of these values in window--display-buffer. Optional post-function is called after the buffer is displayed in the window; the function takes two arguments: an old and new window. Optional string argument echo can be used to add a prefix to the command echo keystrokes that should describe the current prefix state. This returns an "exit function", which can be called with no argument to deactivate this overriding action.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun display-buffer-override-next-command (pre-function &optional post-function echo)
  "Set `display-buffer-overriding-action' for the next command.
`pre-function' is called to prepare the window where the buffer should be
displayed.  This function takes two arguments `buffer' and `alist', and
should return a cons with the displayed window and its type.  See the
meaning of these values in `window--display-buffer'.
Optional `post-function' is called after the buffer is displayed in the
window; the function takes two arguments: an old and new window.
Optional string argument `echo' can be used to add a prefix to the
command echo keystrokes that should describe the current prefix state.
This returns an \"exit function\", which can be called with no argument
to deactivate this overriding action."
  (let* ((old-window (or (minibuffer-selected-window) (selected-window)))
         (new-window nil)
         (minibuffer-depth (minibuffer-depth))
         (obey-display switch-to-buffer-obey-display-actions)
         (clearfun (make-symbol "clear-display-buffer-overriding-action"))
         (postfun (make-symbol "post-display-buffer-override-next-command"))
         (action (lambda (buffer alist)
                   (unless (> (minibuffer-depth) minibuffer-depth)
                     (let* ((ret (funcall pre-function buffer alist))
                            (window (car ret))
                            (type (cdr ret)))
                       (setq new-window (window--display-buffer buffer window
                                                                type alist))
                       ;; Reset display-buffer-overriding-action
                       ;; after the first display-buffer action (bug#39722).
                       (funcall clearfun)
                       new-window))))
         (command this-command)
         (echofun (when echo (lambda () echo)))
         (exitfun
          (lambda ()
            (funcall clearfun)
            (remove-hook 'post-command-hook postfun)
            (remove-hook 'prefix-command-echo-keystrokes-functions echofun)
            (when (functionp post-function)
              (funcall post-function old-window new-window)))))
    (fset clearfun
          (lambda ()
            (setq switch-to-buffer-obey-display-actions obey-display)
            (setcar display-buffer-overriding-action
                    (delq action (car display-buffer-overriding-action)))))
    (fset postfun
          (lambda ()
            (unless (or
                     ;; Remove the hook immediately
                     ;; after exiting the minibuffer.
                     (> (minibuffer-depth) minibuffer-depth)
                     ;; But don't remove immediately after
                     ;; adding the hook by the same command below.
                     (eq this-command command)
                     ;; Don't exit on mouse events in anticipation
                     ;; of more related events like double click.
                     (mouse-event-p last-input-event))
              (funcall exitfun))))
    ;; Call post-function after the next command finishes (bug#49057).
    (add-hook 'post-command-hook postfun)
    (when echofun
      (add-hook 'prefix-command-echo-keystrokes-functions echofun))
    (setq switch-to-buffer-obey-display-actions t)
    (unless (listp (car display-buffer-overriding-action))
      (setcar display-buffer-overriding-action
              (list (car display-buffer-overriding-action))))
    (push action (car display-buffer-overriding-action))
    exitfun))