Function: frame-restack

frame-restack is a byte-compiled function defined in frame.el.gz.

Signature

(frame-restack FRAME1 FRAME2 &optional ABOVE)

Documentation

Restack FRAME1 below FRAME2.

This implies that if both frames are visible and the display areas of these frames overlap, FRAME2 will (partially) obscure FRAME1. If the optional third argument ABOVE is non-nil, restack FRAME1 above FRAME2. This means that if both frames are visible and the display areas of these frames overlap, FRAME1 will
(partially) obscure FRAME2.

This may be thought of as an atomic action performed in two steps: The first step removes FRAME1's window-system window from the display. The second step reinserts FRAME1's window below (above if ABOVE is true) that of FRAME2. Hence the position of FRAME2 in its display's Z (stacking) order relative to all other frames excluding FRAME1 remains unaltered.

Some window managers may refuse to restack windows.

View in manual

Probably introduced at or before Emacs version 26.1.

Source Code

;; Defined in /usr/src/emacs/lisp/frame.el.gz
(defun frame-restack (frame1 frame2 &optional above)
  "Restack FRAME1 below FRAME2.
This implies that if both frames are visible and the display
areas of these frames overlap, FRAME2 will (partially) obscure
FRAME1.  If the optional third argument ABOVE is non-nil, restack
FRAME1 above FRAME2.  This means that if both frames are visible
and the display areas of these frames overlap, FRAME1 will
\(partially) obscure FRAME2.

This may be thought of as an atomic action performed in two
steps: The first step removes FRAME1's window-system window from
the display.  The second step reinserts FRAME1's window
below (above if ABOVE is true) that of FRAME2.  Hence the
position of FRAME2 in its display's Z (stacking) order relative
to all other frames excluding FRAME1 remains unaltered.

Some window managers may refuse to restack windows."
  (if (and (frame-live-p frame1)
           (frame-live-p frame2)
           (equal (frame-parameter frame1 'display)
                  (frame-parameter frame2 'display)))
      (let ((frame-type (framep-on-display frame1)))
        (cond
         ((eq frame-type 'x)
          (x-frame-restack frame1 frame2 above))
         ((eq frame-type 'w32)
          (w32-frame-restack frame1 frame2 above))
         ((eq frame-type 'ns)
          (ns-frame-restack frame1 frame2 above))
         ((eq frame-type 'haiku)
          (haiku-frame-restack frame1 frame2 above))
         ((eq frame-type 'pgtk)
          (pgtk-frame-restack frame1 frame2 above))
         ((eq frame-type 'android)
          (android-frame-restack frame1 frame2 above))
         (t
          (tty-frame-restack frame1 frame2 above))))
    (error "Cannot restack frames")))