Implement default help-echo for mode line.

* lisp/bindings.el: Remove explicit help-echo from format-mode-line.
(mode-line-front-space, mode-line-end-spaces)
(mode-line-misc-info): New variables.
(mode-line-modes, mode-line-position): Move the default value to
the variable definition.
(mode-line-default-help-echo): New defcustom.

* src/buffer.c (buffer_local_value_1): New function, split from
Fbuffer_local_value; can return Qunbound.
(Fbuffer_local_value): Use it.
(Vmode_line_format): Docstring tweaks.

* src/xdisp.c (calc_pixel_width_or_height): Use Fbuffer_local_value.
(note_mode_line_or_margin_highlight): If there is no help echo,
use mode-line-default-help-echo.  Handle the case where the mouse
position is past the end of the mode line string.

* doc/lispref/modes.texi (Mode Line Data): Use "mode line construct"
terminology for consistency.

2 files changed, 165 insertions, 158 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e39b8a64205..5a3b1d3926d 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,13 @@
+2012-06-03  Chong Yidong  <cyd@gnu.org>
+
+	* bindings.el: Remove explicit help text from format-mode-line.
+	It is now supplied by mode-line-default-help-echo.
+	(mode-line-front-space, mode-line-end-spaces)
+	(mode-line-misc-info): New variables.
+	(mode-line-modes, mode-line-position): Move the default value to
+	the variable definition.
+	(mode-line-default-help-echo): New defcustom.
+
 2012-06-02  Stefan Monnier  <monnier@iro.umontreal.ca>
 
 	* simple.el (execute-extended-command): Set real-this-command
diff --git a/lisp/bindings.el b/lisp/bindings.el
index 69d96ab6889..65dd68a4447 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -43,7 +43,6 @@ corresponding to the mode line clicked."
     (with-no-warnings (toggle-read-only))
     (force-mode-line-update)))
 
-
 (defun mode-line-toggle-modified (event)
   "Toggle the buffer-modified flag from the mode-line."
   (interactive "e")
@@ -52,7 +51,6 @@ corresponding to the mode line clicked."
     (set-buffer-modified-p (not (buffer-modified-p)))
     (force-mode-line-update)))
 
-
 (defun mode-line-widen (event)
   "Widen a buffer from the mode-line."
   (interactive "e")
@@ -61,7 +59,6 @@ corresponding to the mode line clicked."
     (widen)
     (force-mode-line-update)))
 
-
 (defvar mode-line-input-method-map
   (let ((map (make-sparse-keymap)))
     (define-key map [mode-line mouse-2]
@@ -81,7 +78,6 @@ corresponding to the mode line clicked."
 	  (describe-current-input-method))))
     (purecopy map)))
 
-
 (defvar mode-line-coding-system-map
   (let ((map (make-sparse-keymap)))
     (define-key map [mode-line mouse-1]
@@ -95,7 +91,6 @@ corresponding to the mode line clicked."
     (purecopy map))
   "Local keymap for the coding-system part of the mode line.")
 
-
 (defun mode-line-change-eol (event)
   "Cycle through the various possible kinds of end-of-line styles."
   (interactive "e")
@@ -130,13 +125,28 @@ corresponding to the mode line clicked."
       (push (cons eol (cons mnemonic desc)) mode-line-eol-desc-cache)
       desc)))
 
-(defvar mode-line-client
-  `(""
-    (:propertize ("" (:eval (if (frame-parameter nil 'client) "@" "")))
-		 help-echo ,(purecopy "emacsclient frame")))
-  "Mode-line control for identifying emacsclient frames.")
-;;;###autoload
-(put 'mode-line-client 'risky-local-variable t)
+
+;;; Mode line contents
+
+(defcustom mode-line-default-help-echo
+  "mouse-1: Select (drag to resize)\n\
+mouse-2: Make current window occupy the whole frame\n\
+mouse-3: Remove current window from display"
+  "Default help text for the mode line.
+If the value is a string, it specifies the tooltip or echo area
+message to display when the mouse is moved over the mode line.
+If the text at the mouse position has a `help-echo' text
+property, that overrides this variable."
+  :type '(choice (const :tag "No help" :value nil) string)
+  :version "24.2"
+  :group 'mode-line)
+
+(defvar mode-line-front-space '(:eval (if (display-graphic-p) " " "-"))
+  "Mode line construct to put at the front of the mode line.
+By default, this construct is displayed right at the beginning of
+the mode line, except that if there is a memory-full message, it
+is displayed first.")
+(put 'mode-line-front-space 'risky-local-variable t)
 
 (defvar mode-line-mule-info
   `(""
@@ -167,7 +177,7 @@ mouse-3: Describe current input method"))
       'mouse-face 'mode-line-highlight
       'local-map mode-line-coding-system-map)
     (:eval (mode-line-eol-desc)))
-  "Mode-line control for displaying information of multilingual environment.
+  "Mode line construct for displaying information of multilingual environment.
 Normally it displays current input method (if any activated) and
 mnemonics of the following coding systems:
   coding system for saving or writing the current buffer
@@ -177,34 +187,17 @@ mnemonics of the following coding systems:
   ;;  coding system for decoding output of buffer process (if any)
   ;;  coding system for encoding text to send to buffer process (if any)."
 )
-
 ;;;###autoload
 (put 'mode-line-mule-info 'risky-local-variable t)
 (make-variable-buffer-local 'mode-line-mule-info)
 
-;; MSDOS frames have window-system, but want the Fn identification.
-(defun mode-line-frame-control ()
-  "Compute mode-line control for frame identification.
-Value is used for `mode-line-frame-identification', which see."
-  (if (or (null window-system)
-	  (eq window-system 'pc))
-      "-%F  "
-    "  "))
-
-;; We need to defer the call to mode-line-frame-control to the time
-;; the mode line is actually displayed.
-(defvar mode-line-frame-identification '(:eval (mode-line-frame-control))
-  "Mode-line control to describe the current frame.")
-;;;###autoload
-(put 'mode-line-frame-identification 'risky-local-variable t)
-
-(defvar mode-line-process nil "\
-Mode-line control for displaying info on process status.
-Normally nil in most modes, since there is no process to display.")
-
+(defvar mode-line-client
+  `(""
+    (:propertize ("" (:eval (if (frame-parameter nil 'client) "@" "")))
+		 help-echo ,(purecopy "emacsclient frame")))
+  "Mode line construct for identifying emacsclient frames.")
 ;;;###autoload
-(put 'mode-line-process 'risky-local-variable t)
-(make-variable-buffer-local 'mode-line-process)
+(put 'mode-line-client 'risky-local-variable t)
 
 (defvar mode-line-modified
   (list (propertize
@@ -232,8 +225,7 @@ Normally nil in most modes, since there is no process to display.")
 	 'local-map (purecopy (make-mode-line-mouse-map
 			       'mouse-1 #'mode-line-toggle-modified))
 	 'mouse-face 'mode-line-highlight))
-  "Mode-line control for displaying whether current buffer is modified.")
-
+  "Mode line construct for displaying whether current buffer is modified.")
 ;;;###autoload
 (put 'mode-line-modified 'risky-local-variable t)
 (make-variable-buffer-local 'mode-line-modified)
@@ -251,24 +243,33 @@ Normally nil in most modes, since there is no process to display.")
 					       "Current directory is remote: "
 					     "Current directory is local: ")
 					   default-directory)))))))
-  "Mode-line flag to show if default-directory for current buffer is remote.")
+  "Mode line construct to indicate a remote buffer.")
 ;;;###autoload
 (put 'mode-line-remote 'risky-local-variable t)
-
 (make-variable-buffer-local 'mode-line-remote)
 
-;; Actual initialization is below.
-(defvar mode-line-position nil
-  "Mode-line control for displaying the position in the buffer.
-Normally displays the buffer percentage and, optionally, the
-buffer size, the line number and the column number.")
+;; MSDOS frames have window-system, but want the Fn identification.
+(defun mode-line-frame-control ()
+  "Compute mode line construct for frame identification.
+Value is used for `mode-line-frame-identification', which see."
+  (if (or (null window-system)
+	  (eq window-system 'pc))
+      "-%F  "
+    "  "))
+
+;; We need to defer the call to mode-line-frame-control to the time
+;; the mode line is actually displayed.
+(defvar mode-line-frame-identification '(:eval (mode-line-frame-control))
+  "Mode line construct to describe the current frame.")
 ;;;###autoload
-(put 'mode-line-position 'risky-local-variable t)
+(put 'mode-line-frame-identification 'risky-local-variable t)
 
-(defvar mode-line-modes nil
-  "Mode-line control for displaying major and minor modes.")
+(defvar mode-line-process nil
+  "Mode line construct for displaying info on process status.
+Normally nil in most modes, since there is no process to display.")
 ;;;###autoload
-(put 'mode-line-modes 'risky-local-variable t)
+(put 'mode-line-process 'risky-local-variable t)
+(make-variable-buffer-local 'mode-line-process)
 
 (defvar mode-line-mode-menu (make-sparse-keymap "Minor Modes") "\
 Menu of mode operations in the mode line.")
@@ -292,6 +293,35 @@ Keymap to display on major mode.")
     map) "\
 Keymap to display on minor modes.")
 
+(defvar mode-line-modes
+  (let ((recursive-edit-help-echo "Recursive edit, type C-M-c to get out"))
+    (list (propertize "%[" 'help-echo recursive-edit-help-echo)
+	  "("
+	  `(:propertize ("" mode-name)
+			help-echo "Major mode\n\
+mouse-1: Display major mode menu\n\
+mouse-2: Show help for major mode\n\
+mouse-3: Toggle minor modes"
+			mouse-face mode-line-highlight
+			local-map ,mode-line-major-mode-keymap)
+	  '("" mode-line-process)
+	  `(:propertize ("" minor-mode-alist)
+			mouse-face mode-line-highlight
+			help-echo "Minor mode\n\
+mouse-1: Display minor mode menu\n\
+mouse-2: Show help for minor mode\n\
+mouse-3: Toggle minor modes"
+			local-map ,mode-line-minor-mode-keymap)
+	  (propertize "%n" 'help-echo "mouse-2: Remove narrowing from the current buffer"
+		      'mouse-face 'mode-line-highlight
+		      'local-map (make-mode-line-mouse-map
+				  'mouse-2 #'mode-line-widen))
+	  ")"
+	  (propertize "%]" 'help-echo recursive-edit-help-echo)
+	  " "))
+  "Mode line construct for displaying major and minor modes.")
+(put 'mode-line-modes 'risky-local-variable t)
+
 (defvar mode-line-column-line-number-mode-map
   (let ((map (make-sparse-keymap))
 	(menu-map (make-sparse-keymap "Toggle Line and Column Number Display")))
@@ -307,114 +337,47 @@ Keymap to display on minor modes.")
     map) "\
 Keymap to display on column and line numbers.")
 
-(let* ((help-echo
-	;; The multi-line message doesn't work terribly well on the
-	;; bottom mode line...  Better ideas?
-	;; 	  "\
-	;; mouse-1: select window, mouse-2: delete others, mouse-3: delete,
-	;; drag-mouse-1: resize, C-mouse-2: split horizontally"
-	"mouse-1: Select (drag to resize)\n\
-mouse-2: Make current window occupy the whole frame\n\
-mouse-3: Remove current window from display")
-       (recursive-edit-help-echo "Recursive edit, type C-M-c to get out")
-       (spaces (propertize " " 'help-echo help-echo))
-       (standard-mode-line-format
-	(list
-	 "%e"
-	 `(:eval (if (display-graphic-p)
-		     ,(propertize " " 'help-echo help-echo)
-		   ,(propertize "-" 'help-echo help-echo)))
-	 'mode-line-mule-info
-	 'mode-line-client
-	 'mode-line-modified
-	 'mode-line-remote
-	 'mode-line-frame-identification
-	 'mode-line-buffer-identification
-	 (propertize "   " 'help-echo help-echo)
-	 'mode-line-position
-	 '(vc-mode vc-mode)
-	 (propertize "  " 'help-echo help-echo)
-	 'mode-line-modes
-	 `(which-func-mode ("" which-func-format ,spaces))
-	 `(global-mode-string ("" global-mode-string ,spaces))
-	 `(:eval (unless (display-graphic-p)
-		   ,(propertize "-%-" 'help-echo help-echo)))))
-       (standard-mode-line-modes
-	(list
-	 (propertize "%[" 'help-echo recursive-edit-help-echo)
-	 (propertize "(" 'help-echo help-echo)
-	 `(:propertize ("" mode-name)
-		       help-echo "Major mode\n\
-mouse-1: Display major mode menu\n\
-mouse-2: Show help for major mode\n\
-mouse-3: Toggle minor modes"
-		       mouse-face mode-line-highlight
-		       local-map ,mode-line-major-mode-keymap)
-	 '("" mode-line-process)
-	 `(:propertize ("" minor-mode-alist)
-		       mouse-face mode-line-highlight
-		       help-echo "Minor mode\n\
-mouse-1: Display minor mode menu\n\
-mouse-2: Show help for minor mode\n\
-mouse-3: Toggle minor modes"
-		       local-map ,mode-line-minor-mode-keymap)
-	 (propertize "%n" 'help-echo "mouse-2: Remove narrowing from the current buffer"
-		     'mouse-face 'mode-line-highlight
-		     'local-map (make-mode-line-mouse-map
-				 'mouse-2 #'mode-line-widen))
-	 (propertize ")" 'help-echo help-echo)
-	 (propertize "%]" 'help-echo recursive-edit-help-echo)
-	 spaces))
-
-       (standard-mode-line-position
-	`((-3 ,(propertize
-		"%p"
-		'local-map mode-line-column-line-number-mode-map
-		'mouse-face 'mode-line-highlight
-		;; XXX needs better description
-		'help-echo "Size indication mode\n\
+(defvar mode-line-position
+  `((-3 ,(propertize
+	  "%p"
+	  'local-map mode-line-column-line-number-mode-map
+	  'mouse-face 'mode-line-highlight
+	  ;; XXX needs better description
+	  'help-echo "Size indication mode\n\
 mouse-1: Display Line and Column Mode Menu"))
-	  (size-indication-mode
-	   (8 ,(propertize
-		" of %I"
-		'local-map mode-line-column-line-number-mode-map
-		'mouse-face 'mode-line-highlight
-		;; XXX needs better description
-		'help-echo "Size indication mode\n\
+    (size-indication-mode
+     (8 ,(propertize
+	  " of %I"
+	  'local-map mode-line-column-line-number-mode-map
+	  'mouse-face 'mode-line-highlight
+	  ;; XXX needs better description
+	  'help-echo "Size indication mode\n\
 mouse-1: Display Line and Column Mode Menu")))
-	  (line-number-mode
-	   ((column-number-mode
-	     (10 ,(propertize
-		   " (%l,%c)"
-		   'local-map mode-line-column-line-number-mode-map
-		   'mouse-face 'mode-line-highlight
-		   'help-echo "Line number and Column number\n\
+    (line-number-mode
+     ((column-number-mode
+       (10 ,(propertize
+	     " (%l,%c)"
+	     'local-map mode-line-column-line-number-mode-map
+	     'mouse-face 'mode-line-highlight
+	     'help-echo "Line number and Column number\n\
 mouse-1: Display Line and Column Mode Menu"))
-	     (6 ,(propertize
-		  " L%l"
-		  'local-map mode-line-column-line-number-mode-map
-		  'mouse-face 'mode-line-highlight
-		  'help-echo "Line Number\n\
+       (6 ,(propertize
+	    " L%l"
+	    'local-map mode-line-column-line-number-mode-map
+	    'mouse-face 'mode-line-highlight
+	    'help-echo "Line Number\n\
 mouse-1: Display Line and Column Mode Menu"))))
-	   ((column-number-mode
-	     (5 ,(propertize
-		  " C%c"
-		  'local-map mode-line-column-line-number-mode-map
-		  'mouse-face 'mode-line-highlight
-		  'help-echo "Column number\n\
-mouse-1: Display Line and Column Mode Menu"))))))))
-
-  (setq-default mode-line-format standard-mode-line-format)
-  (put 'mode-line-format 'standard-value
-       (list `(quote ,standard-mode-line-format)))
-
-  (setq-default mode-line-modes standard-mode-line-modes)
-  (put 'mode-line-modes 'standard-value
-       (list `(quote ,standard-mode-line-modes)))
-
-  (setq-default mode-line-position standard-mode-line-position)
-  (put 'mode-line-position 'standard-value
-       (list `(quote ,standard-mode-line-position))))
+     ((column-number-mode
+       (5 ,(propertize
+	    " C%c"
+	    'local-map mode-line-column-line-number-mode-map
+	    'mouse-face 'mode-line-highlight
+	    'help-echo "Column number\n\
+mouse-1: Display Line and Column Mode Menu"))))))
+  "Mode line construct for displaying the position in the buffer.
+Normally displays the buffer percentage and, optionally, the
+buffer size, the line number and the column number.")
+(put 'mode-line-position 'risky-local-variable t)
 
 (defvar mode-line-buffer-identification-keymap
   ;; Add menu of buffer operations to the buffer identification part
@@ -444,16 +407,50 @@ mouse-3: next buffer")
 		    'mouse-face 'mode-line-highlight
 		    'local-map mode-line-buffer-identification-keymap)))
 
-(defvar mode-line-buffer-identification (propertized-buffer-identification "%12b") "\
-Mode-line control for identifying the buffer being displayed.
+(defvar mode-line-buffer-identification
+  (propertized-buffer-identification "%12b")
+  "Mode line construct for identifying the buffer being displayed.
 Its default value is (\"%12b\") with some text properties added.
 Major modes that edit things other than ordinary files may change this
 \(e.g. Info, Dired,...)")
-
 ;;;###autoload
 (put 'mode-line-buffer-identification 'risky-local-variable t)
 (make-variable-buffer-local 'mode-line-buffer-identification)
 
+(defvar mode-line-misc-info
+  '((which-func-mode ("" which-func-format " "))
+    (global-mode-string ("" global-mode-string " ")))
+  "Mode line construct for miscellaneous information.
+By default, this shows the information specified by
+`which-func-mode' and `global-mode-string'.")
+(put 'mode-line-misc-info 'risky-local-variable t)
+
+(defvar mode-line-end-spaces '(:eval (unless (display-graphic-p) "-%-"))
+  "Mode line construct to put at the end of the mode line.")
+(put 'mode-line-end-spaces 'risky-local-variable t)
+
+;; Default value of the top-level `mode-line-format' variable:
+(let ((standard-mode-line-format
+       (list "%e"
+	     'mode-line-front-space
+	     'mode-line-mule-info
+	     'mode-line-client
+	     'mode-line-modified
+	     'mode-line-remote
+	     'mode-line-frame-identification
+	     'mode-line-buffer-identification
+	     "   "
+	     'mode-line-position
+	     '(vc-mode vc-mode)
+	     "  "
+	     'mode-line-modes
+	     'mode-line-misc-info
+	     'mode-line-end-spaces)))
+  (setq-default mode-line-format standard-mode-line-format)
+  (put 'mode-line-format 'standard-value
+       (list `(quote ,standard-mode-line-format))))
+
+
 (defun mode-line-unbury-buffer (event) "\
 Call `unbury-buffer' in this window."
   (interactive "e")
@@ -551,8 +548,8 @@ Alist saying how to show minor modes in the mode line.
 Each element looks like (VARIABLE STRING);
 STRING is included in the mode line if VARIABLE's value is non-nil.
 
-Actually, STRING need not be a string; any possible mode-line element
-is okay.  See `mode-line-format'.")
+Actually, STRING need not be a string; any mode-line construct is
+okay.  See `mode-line-format'.")
 ;;;###autoload
 (put 'minor-mode-alist 'risky-local-variable t)
 ;; Don't use purecopy here--some people want to change these strings.