Function: frameset--restore-frame

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

Signature

(frameset--restore-frame PARAMETERS WINDOW-STATE FILTERS FORCE-ONSCREEN)

Documentation

Set up and return a frame according to its saved state.

That means either reusing an existing frame or creating one anew. PARAMETERS is the frame's parameter alist; WINDOW-STATE is its window state. For the meaning of FILTERS and FORCE-ONSCREEN, see frameset-restore. Internal use only.

Source Code

;; Defined in /usr/src/emacs/lisp/frameset.el.gz
(defun frameset--restore-frame (parameters window-state filters force-onscreen)
  "Set up and return a frame according to its saved state.
That means either reusing an existing frame or creating one anew.
PARAMETERS is the frame's parameter alist; WINDOW-STATE is its window state.
For the meaning of FILTERS and FORCE-ONSCREEN, see `frameset-restore'.
Internal use only."
  (let* ((fullscreen (cdr (assq 'fullscreen parameters)))
	 (filtered-cfg (frameset-filter-params parameters filters nil))
	 (display (cdr (assq 'display filtered-cfg))) ;; post-filtering
	 alt-cfg frame)

    ;; Use text-pixels for height and width, if available.
    (let ((text-pixel-width (cdr (assq 'frameset--text-pixel-width parameters)))
          (text-pixel-height (cdr (assq 'frameset--text-pixel-height parameters))))
      (when text-pixel-width
        (setf (alist-get 'width filtered-cfg) (cons 'text-pixels text-pixel-width)))
      (when text-pixel-height
        (setf (alist-get 'height filtered-cfg) (cons 'text-pixels text-pixel-height))))

    (when fullscreen
      ;; Currently Emacs has the limitation that it does not record the size
      ;; and position of a frame before maximizing it, so we cannot save &
      ;; restore that info.  Instead, when restoring, we resort to creating
      ;; invisible "fullscreen" frames of default size and then maximizing them
      ;; (and making them visible) which at least is somewhat user-friendly
      ;; when these frames are later de-maximized.
      (let ((width (and (eq fullscreen 'fullheight) (cdr (assq 'width filtered-cfg))))
	    (height (and (eq fullscreen 'fullwidth) (cdr (assq 'height filtered-cfg))))
	    (visible (assq 'visibility filtered-cfg)))
	(setq filtered-cfg (cl-delete-if (lambda (p)
					   (memq p '(visibility fullscreen width height)))
					 filtered-cfg :key #'car))
	(when width
	  (setq filtered-cfg (append `((user-size . t) (width . ,width))
				     filtered-cfg)))
	(when height
	  (setq filtered-cfg (append `((user-size . t) (height . ,height))
				     filtered-cfg)))
	;; These are parameters to apply after creating/setting the frame.
	(push visible alt-cfg)
	(push (cons 'fullscreen fullscreen) alt-cfg)))

    ;; Time to find or create a frame and apply the big bunch of parameters.
    (setq frame (and frameset--reuse-list
		     (frameset--reuse-frame display filtered-cfg)))
    (if frame
	(puthash frame :reused frameset--action-map)
      ;; If a frame needs to be created and it falls partially or fully offscreen,
      ;; sometimes it gets "pushed back" onscreen; however, moving it afterwards is
      ;; allowed.  So we create the frame as invisible and then reapply the full
      ;; parameter alist (including position and size parameters).
      (setq frame (make-frame-on-display display
					 (cons '(visibility)
					       (frameset--initial-params filtered-cfg))))
      (puthash frame :created frameset--action-map))

    ;; Remove `border-width' from the list of parameters.  If it has not
    ;; been assigned via `make-frame-on-display', any attempt to assign
    ;; it now via `modify-frame-parameters' may result in an error on X
    ;; (Bug#28873).
    (setq filtered-cfg (assq-delete-all 'border-width filtered-cfg))

    ;; Try to assign parent-frame right here - it will improve things
    ;; for minibuffer-less child frames.
    (let* ((frame-id (frame-parameter frame 'frameset--parent-frame))
           (parent-frame
            (and frame-id (frameset-frame-with-id frame-id))))
      (when (frame-live-p parent-frame)
        (set-frame-parameter frame 'parent-frame parent-frame)))

    (modify-frame-parameters frame
			     (if (eq (frame-parameter frame 'fullscreen) fullscreen)
				 ;; Workaround for bug#14949
				 (assq-delete-all 'fullscreen filtered-cfg)
			       filtered-cfg))

    ;; If requested, force frames to be onscreen.
    (when (and force-onscreen
	       ;; FIXME: iconified frames should be checked too,
	       ;; but it is impossible without deiconifying them.
	       (not (eq (frame-parameter frame 'visibility) 'icon)))
      (frameset-move-onscreen frame force-onscreen))

    ;; Let's give the finishing touches (visibility, maximization).
    (when alt-cfg (modify-frame-parameters frame alt-cfg))
    ;; Now restore window state.
    (window-state-put window-state (frame-root-window frame) 'safe)
    frame))