From e87fbc07801a4ac291d335f0af957ca32cd26381 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 9 Apr 2016 12:30:59 +0300 Subject: [PATCH] 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. --- doc/emacs/frames.texi | 50 ++++++++++++++++++++------ doc/lispref/display.texi | 76 ++++++++++++++++++++++++++++++++++++++++ doc/lispref/elisp.texi | 1 + doc/lispref/text.texi | 5 ++- 4 files changed, 119 insertions(+), 13 deletions(-) diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 35b3f83ab3..383ae7fd6e 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 9ea9548582..010dcb2fd1 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 4c1541e98c..a3bff0b07a 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 37492929e7..1ad665f0e5 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 -- 2.39.2