(escape-glyph, minibuffer-prompt, button): Add commentary for

[gnu-emacs] / lisp / frame.el

diff --git a/lisp/frame.el b/lisp/frame.el
index 446bda557755aaffdbeb3f22e797b1eea2cae015..2aff4860cf3d70e28e248f55b96354e0453aa07d 100644 (file)
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -135,7 +135,9 @@ Pass it BUFFER as first arg, and (cdr ARGS) gives the rest of the args."
           ;; (set-window-dedicated-p window t)
           window))
        ;; If no window yet, make one in a new frame.
-       (let ((frame (make-frame (append args special-display-frame-alist))))
+       (let ((frame
+             (with-current-buffer buffer
+               (make-frame (append args special-display-frame-alist)))))
         (set-window-buffer (frame-selected-window frame) buffer)
         (set-window-dedicated-p (frame-selected-window frame) t)
         (frame-selected-window frame))))))
@@ -520,7 +522,7 @@ React to settings of `default-frame-alist', `initial-frame-alist' there."
 ;;;; Creation of additional frames, and other frame miscellanea
 
 (defun modify-all-frames-parameters (alist)
-  "modify all current and future frames parameters according to ALIST.
+  "Modify all current and future frames' parameters according to ALIST.
 This changes `default-frame-alist' and possibly `initial-frame-alist'.
 See help of `modify-frame-parameters' for more information."
   (let (element)                       ;; temp
@@ -591,7 +593,7 @@ The functions are run with one arg, the newly created frame.")
 
 ;; Alias, kept temporarily.
 (defalias 'new-frame 'make-frame)
-(make-obsolete 'new-frame 'make-frame "21.4")
+(make-obsolete 'new-frame 'make-frame "22.1")
 
 (defun make-frame (&optional parameters)
   "Return a newly created frame displaying the current buffer.
@@ -612,7 +614,13 @@ You cannot specify either `width' or `height', you must use neither or both.
 
 Before the frame is created (via `frame-creation-function'), functions on the
 hook `before-make-frame-hook' are run.  After the frame is created, functions
-on `after-make-frame-functions' are run with one arg, the newly created frame."
+on `after-make-frame-functions' are run with one arg, the newly created frame.
+
+This function itself does not make the new frame the selected frame.
+The previously selected frame remains selected.  However, the
+window system may select the new frame for its own reasons, for
+instance if the frame appears under the mouse pointer and your
+setup is for focus to follow the pointer."
   (interactive)
   (run-hooks 'before-make-frame-hook)
   (let ((frame (funcall frame-creation-function parameters)))
@@ -789,6 +797,8 @@ where
   "Restore the frames to the state described by CONFIGURATION.
 Each frame listed in CONFIGURATION has its position, size, window
 configuration, and other parameters set as specified in CONFIGURATION.
+However, this function does not restore deleted frames.
+
 Ordinarily, this function deletes all existing frames not
 listed in CONFIGURATION.  But if optional second argument NODELETE
 is given and non-nil, the unwanted frames are iconified instead."
@@ -979,7 +989,8 @@ frame's display)."
      ((eq frame-type 'pc)
       (msdos-mouse-p))
      ((eq system-type 'windows-nt)
-      (> w32-num-mouse-buttons 0))
+      (with-no-warnings
+       (> w32-num-mouse-buttons 0)))
      ((memq frame-type '(x mac))
       t)    ;; We assume X and Mac *always* have a pointing device
      (t
@@ -1032,7 +1043,8 @@ frame's display)."
      ((eq frame-type 'pc)
       ;; MS-DOG frames support selections when Emacs runs inside
       ;; the Windows' DOS Box.
-      (not (null dos-windows-version)))
+      (with-no-warnings
+       (not (null dos-windows-version))))
      ((memq frame-type '(x w32 mac))
       t)    ;; FIXME?
      (t
@@ -1183,7 +1195,7 @@ left untouched.  FRAME nil or omitted means use the selected frame."
 
 ;; miscellaneous obsolescence declarations
 (defvaralias 'delete-frame-hook 'delete-frame-functions)
-(make-obsolete-variable 'delete-frame-hook 'delete-frame-functions "21.4")
+(make-obsolete-variable 'delete-frame-hook 'delete-frame-functions "22.1")
 
 \f
 ;; Highlighting trailing whitespace.
@@ -1241,10 +1253,36 @@ The function `blink-cursor-start' is called when the timer fires.")
 
 (defvar blink-cursor-timer nil
   "Timer started from `blink-cursor-start'.
-This timer calls `blink-cursor' every `blink-cursor-interval' seconds.")
+This timer calls `blink-cursor-timer-function' every
+`blink-cursor-interval' seconds.")
+
+;; The strange sequence below is meant to set both the right temporary
+;; value and the right "standard expression" , according to Custom,
+;; for blink-cursor-mode.  We do not know the standard _evaluated_
+;; value yet, because the standard expression uses values that are not
+;; yet set.  Evaluating it now would yield an error, but we make sure
+;; that it is not evaluated, by ensuring that blink-cursor-mode is set
+;; before the defcustom is evaluated and by using the right :initialize
+;; function.  The correct evaluated standard value will be installed
+;; in startup.el using exactly the same expression as in the defcustom.
+(defvar blink-cursor-mode)
+(unless (boundp 'blink-cursor-mode) (setq blink-cursor-mode nil))
+(defcustom blink-cursor-mode
+  (not (or noninteractive
+          emacs-quick-startup
+          (eq system-type 'ms-dos)
+          (not (memq window-system '(x w32)))))
+  "*Non-nil means Blinking Cursor mode is active."
+  :group 'cursor
+  :tag "Blinking cursor"
+  :type 'boolean
+  :initialize 'custom-initialize-set
+  :set #'(lambda (symbol value)
+          (set-default symbol value)
+          (blink-cursor-mode (or value 0))))
 
-(defvar blink-cursor-mode nil
-  "Non-nil means blinking cursor is active.")
+(defvaralias 'blink-cursor 'blink-cursor-mode)
+(make-obsolete-variable 'blink-cursor 'blink-cursor-mode "22.1")
 
 (defun blink-cursor-mode (arg)
   "Toggle blinking cursor mode.
@@ -1277,18 +1315,6 @@ cursor display.  On a text-only terminal, this is not implemented."
          (setq blink-cursor-mode t))
       (internal-show-cursor nil t))))
 
-;; Note that this is really initialized from startup.el before
-;; the init-file is read.
-
-(defcustom blink-cursor nil
-  "*Non-nil means blinking cursor mode is active."
-  :group 'cursor
-  :tag "Blinking cursor"
-  :type 'boolean
-  :set #'(lambda (symbol value)
-          (set-default symbol value)
-          (blink-cursor-mode (or value 0))))
-
 (defun blink-cursor-start ()
   "Timer function called from the timer `blink-cursor-idle-timer'.
 This starts the timer `blink-cursor-timer', which makes the cursor blink