;;; tooltip.el --- show tooltip windows
-;; Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004,
-;; 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+;; Copyright (C) 1997, 1999-2012 Free Software Foundation, Inc.
;; Author: Gerd Moellmann <gerd@acm.org>
;; Keywords: help c mouse tools
+;; Package: emacs
;; This file is part of GNU Emacs.
(define-minor-mode tooltip-mode
"Toggle Tooltip mode.
-With ARG, turn Tooltip mode on if and only if ARG is positive.
-When this minor mode is enabled, Emacs displays help text
-in a pop-up window for buttons and menu items that you put the mouse on.
-\(However, if `tooltip-use-echo-area' is non-nil, this and
-all pop-up help appears in the echo area.)
-
-When Tooltip mode is disabled, Emacs displays one line of
-the help text in the echo area, and does not make a pop-up window."
+With a prefix argument ARG, enable Tooltip mode if ARG is positive,
+and disable it otherwise. If called from Lisp, enable the mode
+if ARG is omitted or nil.
+
+When this global minor mode is enabled, Emacs displays help
+text (e.g. for buttons and menu items that you put the mouse on)
+in a pop-up window.
+
+When Tooltip mode is disabled, Emacs displays help text in the
+echo area, instead of making a pop-up window."
:global t
;; Even if we start on a text-only terminal, make this non-nil by
;; default because we can open a graphical frame later (multi-tty).
:init-value t
- :initialize 'custom-initialize-safe-default
+ :initialize 'custom-initialize-delay
:group 'tooltip
(unless (or (null tooltip-mode) (fboundp 'x-show-tip))
(error "Sorry, tooltips are not yet available on this system"))
(if tooltip-mode
(progn
(add-hook 'pre-command-hook 'tooltip-hide)
- (add-hook 'tooltip-hook 'tooltip-help-tips))
+ (add-hook 'tooltip-functions 'tooltip-help-tips))
(unless (and (boundp 'gud-tooltip-mode) gud-tooltip-mode)
(remove-hook 'pre-command-hook 'tooltip-hide))
- (remove-hook 'tooltip-hook 'tooltip-help-tips))
+ (remove-hook 'tooltip-functions 'tooltip-help-tips))
(setq show-help-function
(if tooltip-mode 'tooltip-show-help 'tooltip-show-help-non-mode)))
"Frame parameters used for tooltips.
If `left' or `top' parameters are included, they specify the absolute
-position to pop up the tooltip."
+position to pop up the tooltip.
+
+Note that font and color parameters are ignored, and the attributes
+of the `tooltip' face are used instead."
:type 'sexp
:group 'tooltip)
(defcustom tooltip-use-echo-area nil
"Use the echo area instead of tooltip frames for help and GUD tooltips.
-To display multi-line help text in the echo area, set this to t
-and enable `tooltip-mode'."
+This variable is obsolete; instead of setting it to t, disable
+`tooltip-mode' (which has a similar effect)."
:type 'boolean
:group 'tooltip)
+(make-obsolete-variable 'tooltip-use-echo-area
+ "disable Tooltip mode instead" "24.1")
+
\f
;;; Variables that are not customizable.
-(defvar tooltip-hook nil
+(define-obsolete-variable-alias 'tooltip-hook 'tooltip-functions "23.1")
+
+(defvar tooltip-functions nil
"Functions to call to display tooltips.
-Each function is called with one argument EVENT which is a copy of
-the last mouse movement event that occurred.")
+Each function is called with one argument EVENT which is a copy
+of the last mouse movement event that occurred. If one of these
+functions displays the tooltip, it should return non-nil and the
+rest are not called.")
(defvar tooltip-timeout-id nil
"The id of the timeout started when Emacs becomes idle.")
(setq tooltip-timeout-id
(add-timeout (tooltip-delay) 'tooltip-timeout nil)))
-(defun tooltip-timeout (object)
+(defun tooltip-timeout (_object)
"Function called when timer with id `tooltip-timeout-id' fires."
- (run-hook-with-args-until-success 'tooltip-hook
+ (run-hook-with-args-until-success 'tooltip-functions
tooltip-last-mouse-motion-event))
\f
(declare-function x-hide-tip "xfns.c" ())
-(defun tooltip-hide (&optional ignored-arg)
+(defun tooltip-hide (&optional _ignored-arg)
"Hide a tooltip, if one is displayed.
Value is non-nil if tooltip was open."
(tooltip-cancel-delayed-tip)
;;; Tooltip help.
(defvar tooltip-help-message nil
- "The last help message received via `tooltip-show-help'.")
+ "The last help message received via `show-help-function'.
+This is used by `tooltip-show-help' and
+`tooltip-show-help-non-mode'.")
(defvar tooltip-previous-message nil
"The previous content of the echo area.")
(defun tooltip-show-help-non-mode (help)
- "Function installed as `show-help-function' when tooltip is off."
+ "Function installed as `show-help-function' when Tooltip mode is off.
+It is also called if Tooltip mode is on, for text-only displays."
(when (and (not (window-minibuffer-p)) ;Don't overwrite minibuffer contents.
- ;; Don't know how to reproduce it in Elisp:
- ;; Don't overwrite a keystroke echo.
- ;; (NILP (echo_message_buffer) || ok_to_overwrite_keystroke_echo)
- (not cursor-in-echo-area)) ;Don't overwrite a prompt.
+ (not cursor-in-echo-area)) ;Don't overwrite a prompt.
(cond
((stringp help)
- (unless tooltip-previous-message
+ (setq help (replace-regexp-in-string "\n" ", " help))
+ (unless (or tooltip-previous-message
+ (string-equal help (current-message))
+ (and (stringp tooltip-help-message)
+ (string-equal tooltip-help-message
+ (current-message))))
(setq tooltip-previous-message (current-message)))
+ (setq tooltip-help-message help)
(let ((message-truncate-lines t)
(message-log-max nil))
- (message "%s" (replace-regexp-in-string "\n" ", " help))))
+ (message "%s" help)))
((stringp tooltip-previous-message)
(let ((message-log-max nil))
(message "%s" tooltip-previous-message)
(setq tooltip-previous-message nil)))
(t
(message nil)))))
-
(defun tooltip-show-help (msg)
"Function installed as `show-help-function'.
MSG is either a help string to display, or nil to cancel the display."
- (let ((previous-help tooltip-help-message))
- (setq tooltip-help-message msg)
- (cond ((null msg)
- ;; Cancel display. This also cancels a delayed tip, if
- ;; there is one.
- (tooltip-hide))
- ((equal previous-help msg)
- ;; Same help as before (but possibly the mouse has moved).
- ;; Keep what we have.
- )
- (t
- ;; A different help. Remove a previous tooltip, and
- ;; display a new one, with some delay.
- (tooltip-hide)
- (tooltip-start-delayed-tip)))))
-
-(defun tooltip-help-tips (event)
+ (if (display-graphic-p)
+ (let ((previous-help tooltip-help-message))
+ (setq tooltip-help-message msg)
+ (cond ((null msg)
+ ;; Cancel display. This also cancels a delayed tip, if
+ ;; there is one.
+ (tooltip-hide))
+ ((equal previous-help msg)
+ ;; Same help as before (but possibly the mouse has moved).
+ ;; Keep what we have.
+ )
+ (t
+ ;; A different help. Remove a previous tooltip, and
+ ;; display a new one, with some delay.
+ (tooltip-hide)
+ (tooltip-start-delayed-tip))))
+ ;; On text-only displays, try `tooltip-show-help-non-mode'.
+ (tooltip-show-help-non-mode msg)))
+
+(defun tooltip-help-tips (_event)
"Hook function to display a help tooltip.
-This is installed on the hook `tooltip-hook', which is run when
-the timer with id `tooltip-timeout-id' fires.
+This is installed on the hook `tooltip-functions', which
+is run when the timer with id `tooltip-timeout-id' fires.
Value is non-nil if this function handled the tip."
(when (stringp tooltip-help-message)
(tooltip-show tooltip-help-message tooltip-use-echo-area)
(provide 'tooltip)
-;; arch-tag: 3d61135e-4618-4a78-af28-183f6df5636f
;;; tooltip.el ends here
HCoop / bpt / emacs.git / blobdiff