mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-24 10:38:38 +00:00
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.
This commit is contained in:
Eli Zaretskii
parent
9f1786e416
commit
e87fbc0780
@ -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+,
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user