frameset-restore

frameset-restore is an autoloaded compiled Lisp function in `frameset.el'.

(frameset-restore FRAMESET &key PREDICATE FILTERS REUSE-FRAMES FORCE-DISPLAY FORCE-ONSCREEN CLEANUP-FRAMES)

Restore a FRAMESET into the current display(s).

PREDICATE is a function called with two arguments, the parameter alist
and the window-state of the frame being restored, in that order (see
the docstring of the `frameset' defstruct for additional details).
If PREDICATE returns nil, the frame described by that parameter alist
and window-state is not restored.

FILTERS is an alist of parameter filters; if nil, the value of
`frameset-filter-alist' is used instead.

REUSE-FRAMES selects the policy to reuse frames when restoring:
t All existing frames can be reused.
nil No existing frame can be reused.
match Only frames with matching frame ids can be reused.
PRED A predicate function; it receives as argument a live frame,
and must return non-nil to allow reusing it, nil otherwise.

FORCE-DISPLAY can be:
t Frames are restored in the current display.
nil Frames are restored, if possible, in their original displays.
delete Frames in other displays are deleted instead of restored.
PRED A function called with two arguments, the parameter alist and
the window state (in that order). It must return t, nil or
`delete', as above but affecting only the frame that will
be created from that parameter alist.

FORCE-ONSCREEN can be:
t Force onscreen only those frames that are fully offscreen.
nil Do not force any frame back onscreen.
all Force onscreen any frame fully or partially offscreen.
PRED A function called with three arguments,
- the live frame just restored,
- a list (LEFT TOP WIDTH HEIGHT), describing the frame,
- a list (LEFT TOP WIDTH HEIGHT), describing the workarea.
It must return non-nil to force the frame onscreen, nil otherwise.

CLEANUP-FRAMES allows to "clean up" the frame list after restoring a frameset:
t Delete all frames that were not created or restored upon.
nil Keep all frames.
FUNC A function called with two arguments:
- FRAME, a live frame.
- ACTION, which can be one of
:rejected Frame existed, but was not a candidate for reuse.
:ignored Frame existed, was a candidate, but wasn't reused.
:reused Frame existed, was a candidate, and restored upon.
:created Frame didn't exist, was created and restored upon.
Return value is ignored.

Note the timing and scope of the operations described above: REUSE-FRAMES
affects existing frames; PREDICATE, FILTERS and FORCE-DISPLAY affect the frame
being restored before that happens; FORCE-ONSCREEN affects the frame once
it has been restored; and CLEANUP-FRAMES affects all frames alive after the
restoration, including those that have been reused or created anew.

All keyword parameters default to nil.