summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorEli Zaretskii <eliz@gnu.org>2016-04-09 12:30:59 +0300
committerEli Zaretskii <eliz@gnu.org>2016-04-09 12:30:59 +0300
commite87fbc07801a4ac291d335f0af957ca32cd26381 (patch)
treeee860dec60f8b944ae6be93ab71c5e74df166131 /doc
parent9f1786e4165aba30ddb16116c5557a0531233008 (diff)
downloademacs-e87fbc07801a4ac291d335f0af957ca32cd26381.tar.gz
Improve Lisp-level documentation of tooltips
* doc/lispref/display.texi (Tooltips): New section. (Bug#23246) (Display): Update the chapter menu. * doc/lispref/text.texi (Special Properties): Make the "tooltip" index entry more concrete. Change the cross-reference to point to "Tooltips" in the ELisp manual. * doc/lispref/elisp.texi (Top): Update the master menu. * doc/emacs/frames.texi (Tooltips): Include more customization variables. Add a cross-reference to the ELisp manual.
Diffstat (limited to 'doc')
-rw-r--r--doc/emacs/frames.texi50
-rw-r--r--doc/lispref/display.texi76
-rw-r--r--doc/lispref/elisp.texi1
-rw-r--r--doc/lispref/text.texi5
4 files changed, 119 insertions, 13 deletions
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 35b3f83ab33..383ae7fd6ee 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1152,11 +1152,11 @@ change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.
@section Tooltips
@cindex tooltips
- @dfn{Tooltips} are small windows that display text information at
-the current mouse position. They activate when there is a pause in
-mouse movement over some significant piece of text in a window, or the
-mode line, or some other part of the Emacs frame such as a tool bar
-button or menu item.
+ @dfn{Tooltips} are small special frames that display text
+information at the current mouse position. They activate when there
+is a pause in mouse movement over some significant piece of text in a
+window, or the mode line, or some other part of the Emacs frame such
+as a tool bar button or menu item.
@findex tooltip-mode
You can toggle the use of tooltips with the command @kbd{M-x
@@ -1164,11 +1164,41 @@ tooltip-mode}. When Tooltip mode is disabled, the help text is
displayed in the echo area instead. To control the use of tooltips at
startup, customize the variable @code{tooltip-mode}.
-@vindex tooltip-delay
- The variables @code{tooltip-delay} specifies how long Emacs should
-wait before displaying a tooltip. For additional customization
-options for displaying tooltips, use @kbd{M-x customize-group
-@key{RET} tooltip @key{RET}}.
+The following variables provide customization options for tooltip
+display:
+
+@vtable @code
+@item tooltip-delay
+This variable specifies how long Emacs should wait before displaying
+the first tooltip. The value is in seconds.
+
+@item tooltip-short-delay
+This variable specifies how long Emacs should wait before displaying
+subsequent tooltips on different items, having already displayed the
+first tooltip. The value is in seconds.
+
+@item tooltip-hide-delay
+The number of seconds since displaying a tooltip to hide it, if the
+mouse doesn't move.
+
+@item tooltip-x-offset
+@itemx tooltip-y-offset
+The X and Y offsets, in pixels, of the left top corner of the tooltip
+from the mouse pointer position. Note that these are ignored if
+@code{tooltip-frame-parameters} was customized to include,
+respectively, the @code{left} and @code{top} parameters. The values
+of the offsets should be chosen so that the tooltip doesn't cover the
+mouse pointer's hot spot, or it might interfere with clicking the
+mouse.
+
+@item tooltip-frame-parameters
+The frame parameters used for displaying tooltips. @xref{Frame
+Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also
+@ref{Tooltips,,, elisp, The Emacs Lisp Reference Manual}.
+@end vtable
+
+For additional customization options for displaying tooltips, use
+@kbd{M-x customize-group @key{RET} tooltip @key{RET}}.
@vindex x-gtk-use-system-tooltips
If Emacs is built with GTK+ support, it displays tooltips via GTK+,
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9ea9548582f..010dcb2fd1f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -34,6 +34,7 @@ that Emacs presents to the user.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
+* Tooltips:: Tooltip display in Emacs.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
@end menu
@@ -6968,6 +6969,81 @@ indicator of Emacs capabilities on a given display type. Instead, use
@code{display-graphic-p} or any of the other @code{display-*-p}
predicates described in @ref{Display Feature Testing}.
+@node Tooltips
+@section Tooltips
+@cindex tooltips
+@dfn{Tooltips} are special frames (@pxref{Frames}) that are used to
+display helpful hints (a.k.a.@: ``tips'') related to the current
+position of the mouse pointer. Emacs uses tooltips to display help
+strings about active portions of text (@pxref{Special Properties}) and
+about various UI elements, such as menu items (@pxref{Extended Menu
+Items}) and tool-bar buttons (@pxref{Tool Bar}).
+
+@defun tooltip-mode
+Tooltip Mode is a minor mode that enables display of tooltips.
+Turning off this mode causes the tooltips be displayed in the echo
+area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always
+displayed in the echo area.
+@end defun
+
+@vindex x-gtk-use-system-tooltips
+When Emacs is built with GTK+ support, it by default displays tooltips
+using GTK+ functions, and the appearance of the tooltips is then
+controlled by GTK+ settings. GTK+ tooltips can be disabled by
+changing the value of the variable @code{x-gtk-use-system-tooltips} to
+@code{nil}. The rest of this subsection describes how to control
+non-GTK+ tooltips, which are presented by Emacs itself.
+
+Since tooltips are special frames, they have their frame parameters
+(@pxref{Frame Parameters}). Unlike other frames, the frame parameters
+for tooltips are stored in a special variable.
+
+@defvar tooltip-frame-parameters
+This customizable option holds the frame parameters used for
+displaying tooltips. Any font and color parameters are ignored, and
+the corresponding attributes of the @code{tooltip} face are used
+instead. If @code{left} or @code{top} parameters are included, they
+are used as absolute frame-relative coordinates where the tooltip
+should be shown. (Mouse-relative position of the tooltip can be
+customized using the variables described in @ref{Tooltips,,, emacs,
+The GNU Emacs Manual}.) Note that the @code{left} and @code{top}
+parameters, if present, override the values of mouse-relative offsets.
+@end defvar
+
+@vindex tooltip@r{ face}
+The @code{tooltip} face determines the appearance of text shown in
+tooltips. It should generally use a variable-pitch font of size that
+is preferably smaller than the default frame font.
+
+@findex tooltip-help-tips
+@defvar tooltip-functions
+This abnormal hook is a list of functions to call when Emacs needs to
+display a tooltip. Each function is called with a single argument
+@var{event} which is a copy of the last mouse movement event. If a
+function on this list actually displays the tooltip, it should return
+non-@code{nil}, and then the rest of the functions will not be
+called. The default value of this variable is a single function
+@code{tooltip-help-tips}.
+@end defvar
+
+If you write your own function to be put on the
+@code{tooltip-functions} list, you may need to know the buffer of the
+mouse event that triggered the tooltip display. The following
+function provides that information.
+
+@defun tooltip-event-buffer event
+This function returns the buffer over which @var{event} occurred.
+Call it with the argument of the function from
+@code{tooltip-functions} to obtain the buffer whose text triggered the
+tooltip. Note that the event might occur not over a buffer (e.g.,
+over the tool bar), in which case this function will return
+@code{nil}.
+@end defun
+
+Other aspects of tooltip display are controlled by several
+customizable settings; see @ref{Tooltips,,, emacs, The GNU Emacs
+Manual}.
+
@node Bidirectional Display
@section Bidirectional Display
@cindex bidirectional display
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4c1541e98c6..a3bff0b07ac 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1380,6 +1380,7 @@ Emacs Display
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
+* Tooltips:: Tooltip display in Emacs.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 37492929e74..1ad665f0e5b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3202,12 +3202,11 @@ or shorter, higher or lower, wider or narrow, or replaced with an image.
@item help-echo
@kindex help-echo @r{(text property)}
-@cindex tooltip
+@cindex tooltip for help strings
@anchor{Text help-echo}
If text has a string as its @code{help-echo} property, then when you
move the mouse onto that text, Emacs displays that string in the echo
-area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
-Manual}).
+area, or in the tooltip window (@pxref{Tooltips}).
If the value of the @code{help-echo} property is a function, that
function is called with three arguments, @var{window}, @var{object} and