Function: tooltip-show

tooltip-show is a byte-compiled function defined in tooltip.el.gz.

Signature

(tooltip-show TEXT &optional USE-ECHO-AREA TEXT-FACE DEFAULT-FACE)

Documentation

Show a tooltip window displaying TEXT.

Text larger than x-max-tooltip-size is clipped.

If the alist in tooltip-frame-parameters includes left and top parameters, they determine the x and y position where the tooltip is displayed. Otherwise, the tooltip pops at offsets specified by tooltip-x-offset and tooltip-y-offset from the current mouse position.

The text properties of TEXT are also modified to add the appropriate faces before displaying the tooltip. If your code depends on them, you should copy the tooltip string before passing it to this function.

Optional second arg USE-ECHO-AREA non-nil means to show tooltip in echo area.

The third and fourth args TEXT-FACE and DEFAULT-FACE specify faces used to display the tooltip, and default to tooltip if not specified. TEXT-FACE specifies a face used to display text in the tooltip, while DEFAULT-FACE specifies a face that provides the background, foreground and border colors of the tooltip frame.

Note that the last two arguments are not respected when use-system-tooltips is non-nil and Emacs is built with support for system tooltips, such as on NS, Haiku, and with the GTK toolkit.

Probably introduced at or before Emacs version 29.1.

Source Code

;; Defined in /usr/src/emacs/lisp/tooltip.el.gz
(defun tooltip-show (text &optional use-echo-area text-face default-face)
  "Show a tooltip window displaying TEXT.

Text larger than `x-max-tooltip-size' is clipped.

If the alist in `tooltip-frame-parameters' includes `left' and
`top' parameters, they determine the x and y position where the
tooltip is displayed.  Otherwise, the tooltip pops at offsets
specified by `tooltip-x-offset' and `tooltip-y-offset' from the
current mouse position.

The text properties of TEXT are also modified to add the
appropriate faces before displaying the tooltip.  If your code
depends on them, you should copy the tooltip string before
passing it to this function.

Optional second arg USE-ECHO-AREA non-nil means to show tooltip
in echo area.

The third and fourth args TEXT-FACE and DEFAULT-FACE specify
faces used to display the tooltip, and default to `tooltip' if
not specified.  TEXT-FACE specifies a face used to display text
in the tooltip, while DEFAULT-FACE specifies a face that provides
the background, foreground and border colors of the tooltip
frame.

Note that the last two arguments are not respected when
`use-system-tooltips' is non-nil and Emacs is built with support
for system tooltips, such as on NS, Haiku, and with the GTK
toolkit."
  (if (or use-echo-area
          (not (display-graphic-p)))
      (tooltip-show-help-non-mode text)
    (condition-case error
	(let ((params (copy-sequence tooltip-frame-parameters))
	      (fg (face-attribute (or default-face 'tooltip) :foreground))
	      (bg (face-attribute (or default-face 'tooltip) :background)))
	  (when (stringp fg)
	    (setf (alist-get 'foreground-color params) fg)
	    (setf (alist-get 'border-color params) fg))
	  (when (stringp bg)
	    (setf (alist-get 'background-color params) bg))
          ;; Use non-nil APPEND argument below to avoid overriding any
          ;; faces used in our TEXT.  Among other things, this allows
          ;; tooltips to use the `help-key-binding' face used in
          ;; `substitute-command-keys' substitutions.
          (add-face-text-property 0 (length text)
                                  (or text-face 'tooltip) t text)
          (x-show-tip text
		      (selected-frame)
		      params
		      tooltip-hide-delay
		      tooltip-x-offset
		      tooltip-y-offset))
      (error
       (message "Error while displaying tooltip: %s" error)
       (sit-for 1)
       (message "%s" text)))))