new buffer display action: display-buffer-reuse-frame

new buffer display action: display-buffer-reuse-frame

[Stephen Leake]

I'd like to add display-buffer-reuse-frame to window.el:

(defun display-buffer-reuse-frame (buffer alist)
  "Display BUFFER in an existing frame other than the current frame.
If successful, return the window used; otherwise return nil.

If ALIST has a non-nil `inhibit-switch-frame' entry, avoid
raising the frame.

If ALIST has a non-nil `pop-up-frame-parameters' entry, the
corresponding value is an alist of frame parameters to give the
new frame.

If ALIST has a non-nil `frame-predicate' entry, the corresponding
value is a function taking one argument (a frame), returning
non-nil if the frame is a candidate."
  (let* ((predicate (or (cdr (assoc 'frame-predicate alist))
                        (lambda (frame)
                          (and
                           (not (eq frame (selected-frame)))
                           (not (window-dedicated-p
                                 (or
                                  (get-lru-window frame)
                                  (frame-first-window frame)))))
                          )))
	 (frame (car (filtered-frame-list predicate)))
	 (window (and frame (get-lru-window frame))))

    (when window
      (prog1
	  (window--display-buffer
	   buffer window 'frame alist display-buffer-mark-dedicated)
	(unless (cdr (assq 'inhibit-switch-frame alist))
	  (window--maybe-raise-frame frame))))
    ))

This is an alternative to display-buffer-pop-up-frame. I have a couple
of use cases for it, both based on the premise that there are normally
two Emacs frames open. This allows other applications to temporarily
cover one of the frames while still allowing Emacs to be in the
foreground. It also provides another level of buffer placement control.

- Using ediff to review a file for a commit. There are now three frames;
  the ediff control frame, the frame containing the old and current file
  versions under ediff control, and another frame. The user wants to put
  the log edit buffer in the other frame; they specify
  display-buffer-reuse-frame as the action, with a frame predicate that
  excludes the two ediff frames.

- User would like to move a buffer to the other frame. For instance,
  they just used M-. to find the definition of an elisp function, and
  they'd like to return to the use of the function, while keeping the
  definition visible. They specify display-buffer-reuse-frame as the
  action.

Thoughts?
  
-- 
-- Stephe

Re: new buffer display action: display-buffer-reuse-frame

[martin rudalics]

 > I'd like to add display-buffer-reuse-frame to window.el:

This would be a misnomer.  `display-buffer-reuse-window' takes a window
that already shows the buffer and `display-buffer-reuse-frames', albeit
obsolete, meant a similar thing.  `display-buffer-use-some-frame' could
be used.

 > This is an alternative to display-buffer-pop-up-frame. I have a couple
 > of use cases for it, both based on the premise that there are normally
 > two Emacs frames open. This allows other applications to temporarily
 > cover one of the frames while still allowing Emacs to be in the
 > foreground. It also provides another level of buffer placement control.
 >
 > - Using ediff to review a file for a commit. There are now three frames;
 >    the ediff control frame, the frame containing the old and current file
 >    versions under ediff control, and another frame. The user wants to put
 >    the log edit buffer in the other frame; they specify
 >    display-buffer-reuse-frame as the action, with a frame predicate that
 >    excludes the two ediff frames.
 >
 > - User would like to move a buffer to the other frame. For instance,
 >    they just used M-. to find the definition of an elisp function, and
 >    they'd like to return to the use of the function, while keeping the
 >    definition visible. They specify display-buffer-reuse-frame as the
 >    action.
 >
 > Thoughts?

I think you should add it (together with appropriate NEWS and elisp
manual entries).

martin

Re: new buffer display action: display-buffer-reuse-frame

[Stephen Leake]

martin rudalics <rudalics@gmx.at> writes:

>> I'd like to add display-buffer-reuse-frame to window.el:
>
> This would be a misnomer.  `display-buffer-reuse-window' takes a window
> that already shows the buffer and `display-buffer-reuse-frames', albeit
> obsolete, meant a similar thing.  `display-buffer-use-some-frame' could
> be used.

Ok, renamed.

> I think you should add it (together with appropriate NEWS and elisp
> manual entries).

Forgot the NEWS and elisp manual; on the first try; fixed now.

Thanks for your review.

-- 
-- Stephe

Re: new buffer display action: display-buffer-reuse-frame

[martin rudalics]

     * lisp/window.el (display-buffer-use-some-frame): improve doc string

     * doc/lispref/windows.texi (Display Action Functions): add
       display-buffer-use-some-frame

     * etc/NEWS: mention display-buffer-use-some-frame

Please note that ChangeLog entries should be unindented and "complete
sentences starting with a capital and ending with a period".  So

* lisp/window.el (display-buffer-use-some-frame): Improve doc string.

would be the preferred format.

martin

Re: new buffer display action: display-buffer-reuse-frame

[Stephen Leake]

martin rudalics <rudalics@gmx.at> writes:

>     * lisp/window.el (display-buffer-use-some-frame): improve doc string
>
>     * doc/lispref/windows.texi (Display Action Functions): add
>       display-buffer-use-some-frame
>
>     * etc/NEWS: mention display-buffer-use-some-frame
>
> Please note that ChangeLog entries should be unindented and "complete
> sentences starting with a capital and ending with a period".  So
>
> * lisp/window.el (display-buffer-use-some-frame): Improve doc string.
>
> would be the preferred format.

Right. Sorry. Eli had the same comment on earlier commits.

I don't pay attention to "complete sentences" in other projects, and I
haven't figured out how to change that habit for this one.

I'll have to write another commit check hook to do that!


I guess by "unindented" you are refering to the second ine in the
windows.texi entry? So that should be:

* doc/lispref/windows.texi (Display Action Functions): Add
display-buffer-use-some-frame.


Ok. I think indenting makes it easier to read. But the examples in
CONTRIBUTE and
http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs
clearly show "unindented", and standards are important. One more item
for the commit check.

--
-- Stephe

Re: new buffer display action: display-buffer-reuse-frame

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Thu, 30 Jul 2015 10:24:45 -0500
> 
> I guess by "unindented" you are refering to the second ine in the
> windows.texi entry? So that should be:
> 
> * doc/lispref/windows.texi (Display Action Functions): Add
> display-buffer-use-some-frame.
> 
> 
> Ok. I think indenting makes it easier to read.

"git log" indents by itself, so that's not a problem.