Variable: frameset-session-filter-alist

frameset-session-filter-alist is a variable defined in frameset.el.gz.

Value

((name . :never)
 (left . frameset-filter-iconified)
 (minibuffer . frameset-filter-minibuffer)
 (top . frameset-filter-iconified))

Documentation

Minimum set of parameters to filter for live (on-session) framesets.

DO NOT MODIFY. See frameset-filter-alist for a full description.

Source Code

;; Defined in /usr/src/emacs/lisp/frameset.el.gz
;; Filtering

;; What's the deal with these "filter alists"?
;;
;; Let's say that Emacs' frame parameters were never designed as a tool to
;; precisely record (or restore) a frame's state.  They grew organically,
;; and their uses and behaviors reflect their history.  In using them to
;; implement framesets, the unwary implementer, or the prospective package
;; writer willing to use framesets in their code, might fall victim of some
;; unexpected... oddities.
;;
;; You can find frame parameters that:
;;
;; - can be used to get and set some data from the frame's current state
;;   (`height', `width')
;; - can be set at creation time, and setting them afterwards has no effect
;;   (`window-state', `minibuffer')
;; - can be set at creation time, and setting them afterwards will fail with
;;   an error, *unless* you set it to the same value, a noop (`border-width')
;; - act differently when passed at frame creation time, and when set
;;   afterwards (`height')
;; - affect the value of other parameters (`name', `visibility')
;; - can be ignored by window managers (most positional args, like `height',
;;   `width', `left' and `top', and others, like `auto-raise', `auto-lower')
;; - can be set externally in X resources or Window registry (again, most
;;   positional parameters, and also `toolbar-lines', `menu-bar-lines' etc.)
;, - can contain references to live objects (`buffer-list', `minibuffer') or
;;   code (`buffer-predicate')
;; - are set automatically, and cannot be changed (`window-id', `parent-id'),
;;   but setting them produces no error
;; - have a noticeable effect in some window managers, and are ignored in
;;   others (`menu-bar-lines')
;; - can not be safely set in a tty session and then copied back to a GUI
;;   session (`font', `background-color', `foreground-color')
;;
;; etc etc.
;;
;; Which means that, in order to save a parameter alist to disk and read it
;; back later to reconstruct a frame, some processing must be done.  That's
;; what `frameset-filter-params' and the `frameset-*-filter-alist' variables
;; are for.
;;
;; First, a clarification.  The word "filter" in these names refers to both
;; common meanings of filter: to filter out (i.e., to remove), and to pass
;; through a transformation function (think `filter-buffer-substring').
;;
;; `frameset-filter-params' takes a parameter alist PARAMETERS, a filtering
;; alist FILTER-ALIST, and a flag SAVING to indicate whether we are filtering
;; parameters with the intent of saving a frame or restoring it.  It then
;; accumulates an output alist, FILTERED, by checking each parameter in
;; PARAMETERS against FILTER-ALIST and obeying any rule found there.  The
;; absence of a rule just means the parameter/value pair (called CURRENT in
;; filtering functions) is copied to FILTERED as is.  Keyword values :save,
;; :restore and :never tell the function to copy CURRENT to FILTERED in the
;; respective situations, that is, when saving, restoring, or never at all.
;; Values :save and :restore can be useful, for example, if you already
;; have a saved frameset created with some intent, and want to reuse it for
;; a different objective where the expected parameter list has different
;; requirements.
;;
;; Finally, the value can also be a filtering function, or a filtering
;; function plus some arguments.  The function is called for each matching
;; parameter, and receives CURRENT (the parameter/value pair being processed),
;; FILTERED (the output alist so far), PARAMETERS (the full parameter alist),
;; SAVING (the save/restore flag), plus any additional ARGS set along the
;; function in the `frameset-*-filter-alist' entry.  The filtering function
;; then has the possibility to pass along CURRENT, or reject it altogether,
;; or pass back a (NEW-PARAM . NEW-VALUE) pair, which does not even need to
;; refer to the same parameter (so you can filter `width' and return `height'
;; and vice versa, if you're feeling silly and want to mess with the user's
;; mind).  As a help in deciding what to do, the filtering function has
;; access to PARAMETERS, but must not change it in any way.  It also has
;; access to FILTERED, which can be modified at will.  This allows two or
;; more filters to coordinate themselves, because in general there's no way
;; to predict the order in which they will be run.
;;
;; So, which parameters are filtered by default, and why? Let's see.
;;
;; - `buffer-list', `buried-buffer-list', `buffer-predicate': They contain
;;   references to live objects, or in the case of `buffer-predicate', it
;;   could also contain an fbound symbol (a predicate function) that could
;;   not be defined in a later session.
;;
;; - `window-id', `outer-window-id', `parent-id': They are assigned
;;   automatically and cannot be set, so keeping them is harmless, but they
;;   add clutter.  `window-system' is similar: it's assigned at frame
;;   creation, and does not serve any useful purpose later.
;;
;; - `left', `top': Only problematic when saving an iconified frame, because
;;   when the frame is iconified they are set to (- 32000), which doesn't
;;   really help in restoring the frame.  Better to remove them and let the
;;   window manager choose a default position for the frame.
;;
;; - `background-color', `foreground-color': In tty frames they can be set
;;   to "unspecified-bg" and "unspecified-fg", which aren't understood on
;;   GUI sessions.  They have to be filtered out when switching from tty to
;;   a graphical display.
;;
;; - `tty', `tty-type': These are tty-specific.  When switching to a GUI
;;   display they do no harm, but they clutter the parameter alist.
;;
;; - `minibuffer': It can contain a reference to a live window, which cannot
;;   be serialized.  Because of Emacs' idiosyncratic treatment of this
;;   parameter, frames created with (minibuffer . t) have a parameter
;;   (minibuffer . #<window...>), while frames created with
;;   (minibuffer . #<window...>) have (minibuffer . nil), which is madness
;;   but helps to differentiate between minibufferless and "normal" frames.
;;   So, changing (minibuffer . #<window...>) to (minibuffer . t) allows
;;   Emacs to set up the new frame correctly.  Nice, uh?
;;
;; - `name': If this parameter is directly set, `explicit-name' is
;;   automatically set to t, and then `name' no longer changes dynamically.
;;   So, in general, not saving `name' is the right thing to do, though
;;   surely there are applications that will want to override this filter.
;;
;; - `frameset--text-pixel-height', `frameset--text-pixel-width': These are used to
;;   save the pixel width and height of a frame. They are necessary
;;   during restore, but should not be set on the actual frame after
;;   restoring, so `:save' is used to ensure they are only saved.
;;
;; - `font', `fullscreen', `height' and `width': These parameters suffer
;;   from the fact that they are badly mangled when going through a
;;   tty session, though not all in the same way.  When saving a GUI frame
;;   and restoring it in a tty, the height and width of the new frame are
;;   those of the tty screen (let's say 80x25, for example); going back
;;   to a GUI session means getting frames of the tty screen size (so all
;;   your frames are 80 cols x 25 rows).  For `fullscreen' there's a
;;   similar problem, because a tty frame cannot really be fullscreen or
;;   maximized, so the state is lost.  The problem with `font' is a bit
;;   different, because a valid GUI font spec in `font' turns into
;;   (font . "tty") in a tty frame, and when read back into a GUI session
;;   it fails because `font's value is no longer a valid font spec.
;;
;; In most cases, the filtering functions just do the obvious thing: remove
;; CURRENT when it is meaningless to keep it, or pass a modified copy if
;; that helps (as in the case of `minibuffer').
;;
;; The exception are the parameters in the last set, which should survive
;; the roundtrip though tty-land.  The answer is to add "stashing
;; parameters", working in pairs, to shelve the GUI-specific contents and
;; restore it once we're back in pixel country.  That's what functions
;; `frameset-filter-shelve-param' and `frameset-filter-unshelve-param' do.
;;
;; Basically, if you set `frameset-filter-shelve-param' as the filter for
;; a parameter P, it will detect when it is restoring a GUI frame into a
;; tty session, and save P's value in the custom parameter X:P, but only
;; if X:P does not exist already (so it is not overwritten if you enter
;; the tty session more than once).  If you're not switching to a tty
;; frame, the filter just passes CURRENT along.
;;
;; The parameter X:P, on the other hand, must have been setup to be
;; filtered by `frameset-filter-unshelve-param', which unshelves the
;; value: if we're entering a GUI session, returns P instead of CURRENT,
;; while in other cases it just passes it along.
;;
;; The only additional trick is that `frameset-filter-shelve-param' does
;; not set P if switching back to GUI and P already has a value, because
;; it assumes that `frameset-filter-unshelve-param' did set it up.  And
;; `frameset-filter-unshelve-param', when unshelving P, must look into
;; FILTERED to determine if P has already been set and if so, modify it;
;; else just returns P.
;;
;; Currently, the value of X in X:P is `GUI', but you can use any prefix,
;; by passing its symbol as argument in the filter:
;;
;;   (my-parameter frameset-filter-shelve-param MYPREFIX)
;;
;; instead of
;;
;;   (my-parameter . frameset-filter-shelve-param)
;;
;; Note that `frameset-filter-unshelve-param' does not need MYPREFIX
;; because it is available from the parameter name in CURRENT.  Also note
;; that the colon between the prefix and the parameter name is hardcoded.
;; The reason is that X:P is quite readable, and that the colon is a
;; very unusual character in symbol names, other than in initial position
;; in keywords (emacs -Q has only two such symbols, and one of them is a
;; URL).  So the probability of a collision with existing or future
;; symbols is quite insignificant.
;;
;; Now, what about the filter alist variables? There are three of them,
;; though only two sets of parameters:
;;
;; - `frameset-session-filter-alist' contains these filters that allow
;;   saving and restoring framesets in-session, without the need to
;;   serialize the frameset or save it to disk (for example, to save a
;;   frameset in a register and restore it later).  Filters in this
;;   list do not remove live objects, except in `minibuffer', which is
;;   dealt especially by `frameset-save' / `frameset-restore'.
;;
;; - `frameset-persistent-filter-alist' is the whole deal.  It does all
;;   the filtering described above, and the result is ready to be saved on
;;   disk without loss of information.  That's the format used by the
;;   desktop.el package, for example.
;;
;; IMPORTANT: These variables share structure and should NEVER be modified.
;;
;; - `frameset-filter-alist': The value of this variable is the default
;;   value for the FILTERS arguments of `frameset-save' and
;;   `frameset-restore'.  It is set to `frameset-persistent-filter-alist',
;;   though it can be changed by specific applications.
;;
;; How to use them?
;;
;; The simplest way is just do nothing.  The default should work
;; reasonably and sensibly enough.  But, what if you really need a
;; customized filter alist?  Then you can create your own variable
;;
;;   (defvar my-filter-alist
;;     '((my-param1 . :never)
;;       (my-param2 . :save)
;;       (my-param3 . :restore)
;;       (my-param4 . my-filtering-function-without-args)
;;       (my-param5   my-filtering-function-with arg1 arg2)
;;       ;;; many other parameters
;;       )
;;     "My customized parameter filter alist.")
;;
;; or, if you're only changing a few items,
;;
;;   (defvar my-filter-alist
;;     (append '((my-param1 . :never)
;;		 (my-param2 . my-filtering-function))
;;	       frameset-filter-alist)
;;     "My brief customized parameter filter alist.")
;;
;; and pass it to the FILTER arg of the save/restore functions,
;; ALWAYS taking care of not modifying the original lists; if you're
;; going to do any modifying of my-filter-alist, please use
;;
;;   (append '((my-param1 . :never) ...)
;;	     (copy-sequence frameset-filter-alist))
;;
;; One thing you shouldn't forget is that they are alists, so searching
;; in them is sequential.  If you just want to change the default of
;; `name' to allow it to be saved, you can set (name . nil) in your
;; customized filter alist; it will take precedence over the latter
;; setting.  In case you decide that you *always* want to save `name',
;; you can add it to `frameset-filter-alist':
;;
;;   (push '(name . nil) frameset-filter-alist)
;;
;; In certain applications, having a parameter filtering function like
;; `frameset-filter-params' can be useful, even if you're not using
;; framesets.  The interface of `frameset-filter-params' is generic
;; and does not depend of global state, with one exception: it uses
;; the dynamically bound variable `frameset--target-display' to decide
;; if, and how, to modify the `display' parameter of FILTERED.  That
;; should not represent a problem, because it's only meaningful when
;; restoring, and customized uses of `frameset-filter-params' are
;; likely to use their own filter alist and just call
;;
;;   (setq my-filtered (frameset-filter-params my-params my-filters t))
;;
;; In case you want to use it with the standard filters, you can
;; wrap the call to `frameset-filter-params' in a let form to bind
;; `frameset--target-display' to nil or the desired value.
;;

;;;###autoload
(defvar frameset-session-filter-alist
  '((name            . :never)
    (left            . frameset-filter-iconified)
    (minibuffer      . frameset-filter-minibuffer)
    (top             . frameset-filter-iconified))
  "Minimum set of parameters to filter for live (on-session) framesets.
DO NOT MODIFY.  See `frameset-filter-alist' for a full description.")