11.11 Frame-Local Variables

Just as variables can have buffer-local bindings, they can also have frame-local bindings. These bindings belong to one frame, and are in effect when that frame is selected. Frame-local bindings are actually frame parameters: you create a frame-local binding in a specific frame by calling modify-frame-parameters and specifying the variable name as the parameter name.

To enable frame-local bindings for a certain variable, call the function make-variable-frame-local.

Command: make-variable-frame-local variable

Enable the use of frame-local bindings for variable. This does not in itself create any frame-local bindings for the variable; however, if some frame already has a value for variable as a frame parameter, that value automatically becomes a frame-local binding.

If the variable is terminal-local, this function signals an error, because such variables cannot have frame-local bindings as well. See section 29.2 Multiple Displays. A few variables that are implemented specially in Emacs can be (and usually are) buffer-local, but can never be frame-local.

Buffer-local bindings take precedence over frame-local bindings. Thus, consider a variable foo: if the current buffer has a buffer-local binding for foo, that binding is active; otherwise, if the selected frame has a frame-local binding for foo, that binding is active; otherwise, the default binding of foo is active.

Here is an example. First we prepare a few bindings for foo:

(setq f1 (selected-frame)) (make-variable-frame-local 'foo) ;; Make a buffer-local binding for foo in `b1'. (set-buffer (get-buffer-create "b1")) (make-local-variable 'foo) (setq foo '(b 1)) ;; Make a frame-local binding for foo in a new frame. ;; Store that frame in f2. (setq f2 (make-frame)) (modify-frame-parameters f2 '((foo . (f 2))))

Now we examine foo in various contexts. Whenever the buffer `b1' is current, its buffer-local binding is in effect, regardless of the selected frame:

(select-frame f1) (set-buffer (get-buffer-create "b1")) foo => (b 1) (select-frame f2) (set-buffer (get-buffer-create "b1")) foo => (b 1)

Otherwise, the frame gets a chance to provide the binding; when frame f2 is selected, its frame-local binding is in effect:

(select-frame f2) (set-buffer (get-buffer "*scratch*")) foo => (f 2)

When neither the current buffer nor the selected frame provides a binding, the default binding is used:

(select-frame f1) (set-buffer (get-buffer "*scratch*")) foo => nil

When the active binding of a variable is a frame-local binding, setting the variable changes that binding. You can observe the result with frame-parameters:

(select-frame f2) (set-buffer (get-buffer "*scratch*")) (setq foo 'nobody) (assq 'foo (frame-parameters f2)) => (foo . nobody)