-;;; frame.el --- multi-frame management independent of window systems
+;;; frame.el --- multi-frame management independent of window systems -*- lexical-binding:t -*-
-;; Copyright (C) 1993-1994, 1996-1997, 2000-2013 Free Software
-;; Foundation, Inc.
+;; Copyright (C) 1993-1994, 1996-1997, 2000-2014 Free Software Foundation, Inc.
-;; Maintainer: FSF
+;; Maintainer: emacs-devel@gnu.org
;; Keywords: internal
;; Package: emacs
;;; Code:
(eval-when-compile (require 'cl-lib))
-(defvar frame-creation-function-alist
- (list (cons nil
- (if (fboundp 'tty-create-frame-with-faces)
- 'tty-create-frame-with-faces
- (lambda (_parameters)
- (error "Can't create multiple frames without a window system")))))
- "Alist of window-system dependent functions to call to create a new frame.
+;; Dispatch tables for GUI methods.
+
+(defun gui-method--name (base)
+ (intern (format "%s-alist" base)))
+
+(defmacro gui-method (name &optional type)
+ (macroexp-let2 nil type (or type `(framep (selected-frame)))
+ `(alist-get ,type ,(gui-method--name name)
+ (lambda (&rest _args)
+ (error "No method %S for %S frame" ',name ,type)))))
+
+(defmacro gui-method-define (name type fun)
+ `(setf (gui-method ,name ',type) ,fun))
+
+(defmacro gui-method-declare (name &optional tty-fun doc)
+ (declare (doc-string 3) (indent 2))
+ `(defvar ,(gui-method--name name)
+ ,(if tty-fun `(list (cons t ,tty-fun))) ,doc))
+
+(defmacro gui-call (name &rest args)
+ `(funcall (gui-method ,name) ,@args))
+
+(gui-method-declare frame-creation-function
+ #'tty-create-frame-with-faces
+ "Method for window-system dependent functions to create a new frame.
The window system startup file should add its frame creation
-function to this list, which should take an alist of parameters
+function to this method, which should take an alist of parameters
as its argument.")
(defvar window-system-default-frame-alist nil
"Window-system dependent default frame parameters.
The value should be an alist of elements (WINDOW-SYSTEM . ALIST),
-where WINDOW-SYSTEM is a window system symbol (see `window-system')
+where WINDOW-SYSTEM is a window system symbol (as returned by `framep')
and ALIST is a frame parameter alist like `default-frame-alist'.
Then, for frames on WINDOW-SYSTEM, any parameters specified in
ALIST supersede the corresponding parameters specified in
(delete-frame frame t)
;; Gildea@x.org says it is ok to ask questions before terminating.
(save-buffers-kill-emacs))))
+
+(defun handle-focus-in (_event)
+ "Handle a focus-in event.
+Focus-in events are usually bound to this function.
+Focus-in events occur when a frame has focus, but a switch-frame event
+is not generated.
+This function runs the hook `focus-in-hook'."
+ (interactive "e")
+ (run-hooks 'focus-in-hook))
+
+(defun handle-focus-out (_event)
+ "Handle a focus-out event.
+Focus-out events are usually bound to this function.
+Focus-out events occur when no frame has focus.
+This function runs the hook `focus-out-hook'."
+ (interactive "e")
+ (run-hooks 'focus-out-hook))
\f
;;;; Arrangement of frames at startup
;; 3) Once the init file is done, we apply any newly set parameters
;; in initial-frame-alist to the frame.
-;; These are now called explicitly at the proper times,
-;; since that is easier to understand.
-;; Actually using hooks within Emacs is bad for future maintenance. --rms.
-;; (add-hook 'before-init-hook 'frame-initialize)
-;; (add-hook 'window-setup-hook 'frame-notice-user-settings)
-
;; If we create the initial frame, this is it.
(defvar frame-initial-frame nil)
(progn
(setq frame-initial-frame-alist
(append initial-frame-alist default-frame-alist nil))
- (or (assq 'horizontal-scroll-bars frame-initial-frame-alist)
- (setq frame-initial-frame-alist
- (cons '(horizontal-scroll-bars . t)
- frame-initial-frame-alist)))
(setq frame-initial-frame-alist
(cons (cons 'window-system initial-window-system)
frame-initial-frame-alist))
(declare-function tool-bar-mode "tool-bar" (&optional arg))
+(defalias 'tool-bar-lines-needed 'tool-bar-height)
+
;; startup.el calls this function after loading the user's init
;; file. Now default-frame-alist and initial-frame-alist contain
;; information to which we must react; do what needs to be done.
;; If the initial frame is still around, apply initial-frame-alist
;; and default-frame-alist to it.
(when (frame-live-p frame-initial-frame)
-
;; When tool-bar has been switched off, correct the frame size
;; by the lines added in x-create-frame for the tool-bar and
;; switch `tool-bar-mode' off.
(when (display-graphic-p)
- (let ((tool-bar-lines (or (assq 'tool-bar-lines initial-frame-alist)
- (assq 'tool-bar-lines window-system-frame-alist)
- (assq 'tool-bar-lines default-frame-alist))))
- (when (and tool-bar-originally-present
- (or (null tool-bar-lines)
- (null (cdr tool-bar-lines))
- (eq 0 (cdr tool-bar-lines))))
- (let* ((char-height (frame-char-height frame-initial-frame))
- (image-height tool-bar-images-pixel-height)
- (margin (cond ((and (consp tool-bar-button-margin)
- (integerp (cdr tool-bar-button-margin))
- (> tool-bar-button-margin 0))
- (cdr tool-bar-button-margin))
- ((and (integerp tool-bar-button-margin)
- (> tool-bar-button-margin 0))
- tool-bar-button-margin)
- (t 0)))
- (relief (if (and (integerp tool-bar-button-relief)
- (> tool-bar-button-relief 0))
- tool-bar-button-relief 3))
- (lines (/ (+ image-height
- (* 2 margin)
- (* 2 relief)
- (1- char-height))
- char-height))
- (height (frame-parameter frame-initial-frame 'height))
- (newparms (list (cons 'height (- height lines))))
- (initial-top (cdr (assq 'top
- frame-initial-geometry-arguments)))
+ (let ((tool-bar-lines
+ (or (assq 'tool-bar-lines initial-frame-alist)
+ (assq 'tool-bar-lines window-system-frame-alist)
+ (assq 'tool-bar-lines default-frame-alist))))
+ ;; Shrink frame by its initial tool bar height iff either zero
+ ;; tool bar lines have been requested in one of the frame's
+ ;; alists or tool bar mode has been turned off explicitly in
+ ;; the user's init file.
+ (when (and tool-bar-lines
+ (> frame-initial-frame-tool-bar-height 0)
+ (or (not tool-bar-mode)
+ (null (cdr tool-bar-lines))
+ (eq 0 (cdr tool-bar-lines))))
+ (set-frame-height
+ frame-initial-frame (- (frame-text-height frame-initial-frame)
+ frame-initial-frame-tool-bar-height)
+ nil t)
+ (let* ((initial-top
+ (cdr (assq 'top frame-initial-geometry-arguments)))
(top (frame-parameter frame-initial-frame 'top)))
(when (and (consp initial-top) (eq '- (car initial-top)))
(let ((adjusted-top
- (cond ((and (consp top)
- (eq '+ (car top)))
- (list '+
- (+ (cadr top)
- (* lines char-height))))
- ((and (consp top)
- (eq '- (car top)))
- (list '-
- (- (cadr top)
- (* lines char-height))))
- (t (+ top (* lines char-height))))))
- (setq newparms
- (append newparms
- `((top . ,adjusted-top))
- nil))))
- (modify-frame-parameters frame-initial-frame newparms)
- (tool-bar-mode -1)))))
+ (cond
+ ((and (consp top) (eq '+ (car top)))
+ (list '+ (+ (cadr top)
+ frame-initial-frame-tool-bar-height)))
+ ((and (consp top) (eq '- (car top)))
+ (list '- (- (cadr top)
+ frame-initial-frame-tool-bar-height)))
+ (t (+ top frame-initial-frame-tool-bar-height)))))
+ (modify-frame-parameters
+ frame-initial-frame '((top . adjusted-top))))))
+ (tool-bar-mode -1))))
;; The initial frame we create above always has a minibuffer.
;; If the user wants to remove it, or make it a minibuffer-only
"Return some frame other than the current frame.
Create one if necessary. Note that the minibuffer frame, if separate,
is not considered (see `next-frame')."
- (let ((s (if (equal (next-frame (selected-frame)) (selected-frame))
- (make-frame)
- (next-frame (selected-frame)))))
- s))
+ (if (equal (next-frame) (selected-frame)) (make-frame) (next-frame)))
(defun next-multiframe-window ()
"Select the next window, regardless of which frame it is on."
(defun window-system-for-display (display)
"Return the window system for DISPLAY.
Return nil if we don't know how to interpret DISPLAY."
- (cl-loop for descriptor in display-format-alist
- for pattern = (car descriptor)
- for system = (cdr descriptor)
- when (string-match-p pattern display) return system))
+ ;; MS-Windows doesn't know how to create a GUI frame in a -nw session.
+ (if (and (eq system-type 'windows-nt)
+ (null (window-system)))
+ nil
+ (cl-loop for descriptor in display-format-alist
+ for pattern = (car descriptor)
+ for system = (cdr descriptor)
+ when (string-match-p pattern display) return system)))
(defun make-frame-on-display (display &optional parameters)
"Make a frame on display DISPLAY.
(define-obsolete-function-alias 'new-frame 'make-frame "22.1")
(defvar frame-inherited-parameters '()
- ;; FIXME: Shouldn't we add `font' here as well?
"Parameters `make-frame' copies from the `selected-frame' to the new frame.")
+(defvar x-display-name)
+
(defun make-frame (&optional parameters)
"Return a newly created frame displaying the current buffer.
Optional argument PARAMETERS is an alist of frame parameters for
((assq 'terminal parameters)
(let ((type (terminal-live-p (cdr (assq 'terminal parameters)))))
(cond
- ((eq type t) nil)
- ((eq type nil) (error "Terminal %s does not exist"
- (cdr (assq 'terminal parameters))))
+ ((null type) (error "Terminal %s does not exist"
+ (cdr (assq 'terminal parameters))))
(t type))))
((assq 'window-system parameters)
(cdr (assq 'window-system parameters)))
(display
(or (window-system-for-display display)
- (error "Don't know how to interpret display \"%S\""
+ (error "Don't know how to interpret display %S"
display)))
(t window-system)))
- (frame-creation-function (cdr (assq w frame-creation-function-alist)))
(oldframe (selected-frame))
(params parameters)
frame)
- (unless frame-creation-function
- (error "Don't know how to create a frame on window system %s" w))
(unless (get w 'window-system-initialized)
- (funcall (cdr (assq w window-system-initialization-alist)) display)
+ (funcall (gui-method window-system-initialization w) display)
(setq x-display-name display)
(put w 'window-system-initialized t))
(push p params)))
;; Now make the frame.
(run-hooks 'before-make-frame-hook)
- (setq frame (funcall frame-creation-function params))
+ (setq frame
+ (funcall (gui-method frame-creation-function (or w t)) params))
(normal-erase-is-backspace-setup-frame frame)
;; Inherit the original frame's parameters.
(dolist (param frame-inherited-parameters)
(nreverse frame-initial-geometry-arguments))
(cdr param-list))
-(declare-function x-focus-frame "xfns.c" (frame))
+(declare-function x-focus-frame "frame.c" (frame))
(defun select-frame-set-input-focus (frame &optional norecord)
"Select FRAME, raise it, and set input focus, if possible.
"The brightness of the background.
Set this to the symbol `dark' if your background color is dark,
`light' if your background is light, or nil (automatic by default)
-if you want Emacs to examine the brightness for you. Don't set this
-variable with `setq'; this won't have the expected effect."
+if you want Emacs to examine the brightness for you.
+
+If you change this without using customize, you should use
+`frame-set-background-mode' to update existing frames;
+e.g. (mapc 'frame-set-background-mode (frame-list))."
:group 'faces
:set #'(lambda (var value)
(set-default var value)
(declare-function x-get-resource "frame.c"
(attribute class &optional component subclass))
+;; Only used if window-system is not null.
+(declare-function x-display-grayscale-p "xfns.c" (&optional terminal))
+
(defvar inhibit-frame-set-background-mode nil)
(defun frame-set-background-mode (frame &optional keep-face-specs)
If FRAMES is nil, apply the font to the selected frame only.
If FRAMES is non-nil, it should be a list of frames to act upon,
-or t meaning all graphical frames. Also, if FRAME is non-nil,
-alter the user's Customization settings as though the
-font-related attributes of the `default' face had been \"set in
-this session\", so that the font is applied to future frames."
+or t meaning all existing graphical frames.
+Also, if FRAMES is non-nil, alter the user's Customization settings
+as though the font-related attributes of the `default' face had been
+\"set in this session\", so that the font is applied to future frames."
(interactive
(let* ((completion-ignore-case t)
(font (completing-read "Font name: "
\f
;;;; Frame/display capabilities.
-(defun selected-terminal ()
- "Return the terminal that is now selected."
- (frame-terminal (selected-frame)))
(declare-function msdos-mouse-p "dosfns.c")
xterm-mouse-mode)
;; t-mouse is distributed with the GPM package. It doesn't have
;; a toggle.
- (featurep 't-mouse))))))
+ (featurep 't-mouse)
+ ;; No way to check whether a w32 console has a mouse, assume
+ ;; it always does.
+ (boundp 'w32-use-full-screen-buffer))))))
(defun display-popup-menus-p (&optional display)
"Return non-nil if popup menus are supported on DISPLAY.
DISPLAY can be a display name, a frame, or nil (meaning the selected
frame's display).
Support for popup menus requires that the mouse be available."
- (and
- (let ((frame-type (framep-on-display display)))
- (memq frame-type '(x w32 pc ns)))
- (display-mouse-p display)))
+ (display-mouse-p display))
(defun display-graphic-p (&optional display)
"Return non-nil if DISPLAY is a graphic display.
(let ((frame-type (framep-on-display display)))
(cond
((eq frame-type 'pc)
- ;; MS-DOG frames support selections when Emacs runs inside
- ;; the Windows' DOS Box.
+ ;; MS-DOS frames support selections when Emacs runs inside
+ ;; a Windows DOS Box.
(with-no-warnings
(not (null dos-windows-version))))
((memq frame-type '(x w32 ns))
- t) ;; FIXME?
+ t)
(t
nil))))
(declare-function x-display-screens "xfns.c" (&optional terminal))
(defun display-screens (&optional display)
- "Return the number of screens associated with DISPLAY."
+ "Return the number of screens associated with DISPLAY.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
(defun display-pixel-height (&optional display)
"Return the height of DISPLAY's screen in pixels.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
For character terminals, each character counts as a single pixel.
+
For graphical terminals, note that on \"multi-monitor\" setups this
refers to the pixel height for all physical monitors associated
with DISPLAY. To get information for each physical monitor, use
(defun display-pixel-width (&optional display)
"Return the width of DISPLAY's screen in pixels.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
For character terminals, each character counts as a single pixel.
+
For graphical terminals, note that on \"multi-monitor\" setups this
refers to the pixel width for all physical monitors associated
with DISPLAY. To get information for each physical monitor, use
(defcustom display-mm-dimensions-alist nil
"Alist for specifying screen dimensions in millimeters.
-The dimensions will be used for `display-mm-height' and
-`display-mm-width' if defined for the respective display.
+The functions `display-mm-height' and `display-mm-width' consult
+this list before asking the system.
-Each element of the alist has the form (display . (width . height)),
-e.g. (\":0.0\" . (287 . 215)).
+Each element has the form (DISPLAY . (WIDTH . HEIGHT)), e.g.
+\(\":0.0\" . (287 . 215)).
-If `display' equals t, it specifies dimensions for all graphical
-displays not explicitly specified."
+If `display' is t, it specifies dimensions for all graphical displays
+not explicitly specified."
:version "22.1"
:type '(alist :key-type (choice (string :tag "Display name")
(const :tag "Default" t))
(defun display-mm-height (&optional display)
"Return the height of DISPLAY's screen in millimeters.
-System values can be overridden by `display-mm-dimensions-alist'.
-If the information is unavailable, value is nil.
+If the information is unavailable, this function returns nil.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
+You can override what the system thinks the result should be by
+adding an entry to `display-mm-dimensions-alist'.
+
For graphical terminals, note that on \"multi-monitor\" setups this
refers to the height in millimeters for all physical monitors
associated with DISPLAY. To get information for each physical
(defun display-mm-width (&optional display)
"Return the width of DISPLAY's screen in millimeters.
-System values can be overridden by `display-mm-dimensions-alist'.
-If the information is unavailable, value is nil.
+If the information is unavailable, this function returns nil.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display.
+
+You can override what the system thinks the result should be by
+adding an entry to `display-mm-dimensions-alist'.
+
For graphical terminals, note that on \"multi-monitor\" setups this
refers to the width in millimeters for all physical monitors
associated with DISPLAY. To get information for each physical
(declare-function x-display-backing-store "xfns.c" (&optional terminal))
+;; In NS port, the return value may be `buffered', `retained', or
+;; `non-retained'. See src/nsfns.m.
(defun display-backing-store (&optional display)
"Return the backing store capability of DISPLAY's screen.
The value may be `always', `when-mapped', `not-useful', or nil if
-the question is inapplicable to a certain kind of display."
+the question is inapplicable to a certain kind of display.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
(declare-function x-display-save-under "xfns.c" (&optional terminal))
(defun display-save-under (&optional display)
- "Return non-nil if DISPLAY's screen supports the SaveUnder feature."
+ "Return non-nil if DISPLAY's screen supports the SaveUnder feature.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
(declare-function x-display-planes "xfns.c" (&optional terminal))
(defun display-planes (&optional display)
- "Return the number of planes supported by DISPLAY."
+ "Return the number of planes supported by DISPLAY.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
(declare-function x-display-color-cells "xfns.c" (&optional terminal))
(defun display-color-cells (&optional display)
- "Return the number of color cells supported by DISPLAY."
+ "Return the number of color cells supported by DISPLAY.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
(defun display-visual-class (&optional display)
"Return the visual class of DISPLAY.
The value is one of the symbols `static-gray', `gray-scale',
-`static-color', `pseudo-color', `true-color', or `direct-color'."
+`static-color', `pseudo-color', `true-color', or `direct-color'.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((memq frame-type '(x w32 ns))
physical monitors. Every non-tip frame (including invisible one)
in a graphical display is dominated by exactly one physical
monitor at a time, though it can span multiple (or no) physical
-monitors."
+monitors.
+If DISPLAY is omitted or nil, it defaults to the selected frame's display."
(let ((frame-type (framep-on-display display)))
(cond
((eq frame-type 'x)
:group 'cursor)
(defcustom blink-cursor-blinks 10
- "How many times to blink before using a solid cursor on NS and X.
+ "How many times to blink before using a solid cursor on NS, X, and MS-Windows.
Use 0 or negative value to blink forever."
:version "24.4"
:type 'integer
:group 'cursor)
(defvar blink-cursor-blinks-done 1
- "Number of blinks done since we started blinking on NS and X")
+ "Number of blinks done since we started blinking on NS, X, and MS-Windows.")
(defvar blink-cursor-idle-timer nil
"Timer started after `blink-cursor-delay' seconds of Emacs idle time.
"Timer function of timer `blink-cursor-timer'."
(internal-show-cursor nil (not (internal-show-cursor-p)))
;; Each blink is two calls to this function.
- (when (memq window-system '(x ns w32))
- (setq blink-cursor-blinks-done (1+ blink-cursor-blinks-done))
- (when (and (> blink-cursor-blinks 0)
- (<= (* 2 blink-cursor-blinks) blink-cursor-blinks-done))
- (blink-cursor-suspend)
- (add-hook 'post-command-hook 'blink-cursor-check))))
+ (setq blink-cursor-blinks-done (1+ blink-cursor-blinks-done))
+ (when (and (> blink-cursor-blinks 0)
+ (<= (* 2 blink-cursor-blinks) blink-cursor-blinks-done))
+ (blink-cursor-suspend)
+ (add-hook 'post-command-hook 'blink-cursor-check)))
(defun blink-cursor-end ()
(setq blink-cursor-timer nil)))
(defun blink-cursor-suspend ()
- "Suspend cursor blinking on NS, X and W32.
+ "Suspend cursor blinking.
This is called when no frame has focus and timers can be suspended.
Timers are restarted by `blink-cursor-check', which is called when a
frame receives focus."
- (when (memq window-system '(x ns w32))
- (blink-cursor-end)
- (when blink-cursor-idle-timer
- (cancel-timer blink-cursor-idle-timer)
- (setq blink-cursor-idle-timer nil))))
+ (blink-cursor-end)
+ (when blink-cursor-idle-timer
+ (cancel-timer blink-cursor-idle-timer)
+ (setq blink-cursor-idle-timer nil)))
(defun blink-cursor-check ()
"Check if cursor blinking shall be restarted.
positive, and disable it otherwise. If called from Lisp, enable
the mode if ARG is omitted or nil.
+If the value of `blink-cursor-blinks' is positive (10 by default),
+the cursor stops blinking after that number of blinks, if Emacs
+gets no input during that time.
+
+See also `blink-cursor-interval' and `blink-cursor-delay'.
+
This command is effective only on graphical frames. On text-only
terminals, cursor blinking is controlled by the terminal."
:init-value (not (or noninteractive
:initialize 'custom-initialize-delay
:group 'cursor
:global t
- (if blink-cursor-idle-timer (cancel-timer blink-cursor-idle-timer))
- (setq blink-cursor-idle-timer nil)
- (blink-cursor-end)
+ (blink-cursor-suspend)
+ (remove-hook 'focus-in-hook #'blink-cursor-check)
+ (remove-hook 'focus-out-hook #'blink-cursor-suspend)
(when blink-cursor-mode
- ;; Hide the cursor.
- ;;(internal-show-cursor nil nil)
+ (add-hook 'focus-in-hook #'blink-cursor-check)
+ (add-hook 'focus-out-hook #'blink-cursor-suspend)
(setq blink-cursor-idle-timer
(run-with-idle-timer blink-cursor-delay
blink-cursor-delay
- 'blink-cursor-start))))
+ #'blink-cursor-start))))
\f
;; Frame maximization/fullscreen