procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve wording of documentation of click events

Browse source 
* doc/lispref/commands.texi (Click Events, Accessing Mouse):
Improve and clarify wording.  (Bug#36232)
This commit is contained in:
Eli Zaretskii 2019-06-16 18:29:21 +03:00
parent bea31a3794
commit 4701e0663e
1 changed files with 37 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
doc/lispref/commands.texi
View file

@ -1395,9 +1395,9 @@ The time at which the event occurred, as an integer number of
milliseconds since a system-dependent initial time.
@item @var{object}
Either @code{nil} if there is no string-type text property at the
click position, or a cons cell of the form (@var{string}
. @var{string-pos}) if there is one:
Either @code{nil}, which means the click occurred on buffer text, or a
cons cell of the form @w{(@var{string} . @var{string-pos})} if there
is a string from a text property or an overlay at the click position.
@table @asis
@item @var{string}
@ -1428,15 +1428,15 @@ clicks on margins, @var{col} is measured from the left edge of the
margin area and @var{row} is measured from the top of the margin area.
@item @var{image}
This is the image object on which the click occurred. It is either
@code{nil} if there is no image at the position clicked on, or it is
an image object as returned by @code{find-image} if click was in an image.
If there is an image at the click location, this is the image object
as returned by @code{find-image} (@pxref{Defining Images}); otherwise
this is @code{nil}.
@item @var{dx}, @var{dy}
These are the pixel coordinates of the click, relative to
the top left corner of @var{object}, which is @code{(0 . 0)}. If
@var{object} is @code{nil}, the coordinates are relative to the top
left corner of the character glyph clicked on.
These are the pixel coordinates of the click, relative to the top left
corner of @var{object}, which is @code{(0 . 0)}. If @var{object} is
@code{nil}, which stands for a buffer, the coordinates are relative to
the top left corner of the character glyph clicked on.
@item @var{width}, @var{height}
These are the pixel width and height of @var{object} or, if this is
@ -2038,8 +2038,8 @@ position such events have.
@defun posnp object
This function returns non-@code{nil} if @var{object} is a mouse
position list, in either of the formats documented in @ref{Click
Events}); and @code{nil} otherwise.
position list, in the format documented in @ref{Click Events}); and
@code{nil} otherwise.
@end defun
@cindex mouse position list, accessing
@ -2067,8 +2067,8 @@ is undefined.
@defun posn-x-y position
Return the pixel-based x and y coordinates in @var{position}, as a
cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
to the window given by @code{posn-window}.
cons cell @w{@code{(@var{x} . @var{y})}}. These coordinates are
relative to the window given by @code{posn-window}.
This example shows how to convert the window-relative coordinates in
the text area of a window into frame-relative coordinates:
@ -2086,11 +2086,11 @@ POSITION is assumed to lie in a window text area."
@end defun
@defun posn-col-row position
This function returns a cons cell @code{(@var{col} . @var{row})},
This function returns a cons cell @w{@code{(@var{col} . @var{row})}},
containing the estimated column and row corresponding to buffer
position in @var{position}. The return value is given in units of the
frame's default character width and default line height (including
spacing), as computed from the @var{x} and @var{y} values
position described by @var{position}. The return value is given in
units of the frame's default character width and default line height
(including spacing), as computed from the @var{x} and @var{y} values
corresponding to @var{position}. (So, if the actual characters have
non-default sizes, the actual row and column may differ from these
computed values.)
@ -2102,7 +2102,7 @@ Lines}), it is @emph{not} included in the @var{row} count.
@defun posn-actual-col-row position
Return the actual row and column in @var{position}, as a cons cell
@code{(@var{col} . @var{row})}. The values are the actual row and
@w{@code{(@var{col} . @var{row})}}. The values are the actual row and
column numbers in the window given by @var{position}. @xref{Click
Events}, for details. The function returns @code{nil} if
@var{position} does not include actual position values; in that case
@ -2115,33 +2115,37 @@ character units, use @code{posn-col-row} instead.
@end defun
@defun posn-string position
Return the string object in @var{position}, either @code{nil}, or a
cons cell @code{(@var{string} . @var{string-pos})}.
Return the string object described by @var{position}, either
@code{nil} (which means @var{position} describes buffer text), or a
cons cell @w{@code{(@var{string} . @var{string-pos})}}.
@end defun
@defun posn-image position
Return the image object in @var{position}, either @code{nil}, or an
image @code{(image ...)}.
Return the image object in @var{position}, either @code{nil} (if
there's no image at @var{position}), or an image spec @w{@code{(image
@dots{})}}.
@end defun
@defun posn-object position
Return the image or string object in @var{position}, either
@code{nil}, an image @code{(image ...)}, or a cons cell
@code{(@var{string} . @var{string-pos})}.
Return the image or string object described by @var{position}, either
@code{nil} (which means @var{position} describes buffer text), an
image @w{@code{(image @dots{})}}, or a cons cell
@w{@code{(@var{string} . @var{string-pos})}}.
@end defun
@defun posn-object-x-y position
Return the pixel-based x and y coordinates relative to the upper left
corner of the object in @var{position} as a cons cell @code{(@var{dx}
. @var{dy})}. If the @var{position} is on buffer text, return the
relative position of the buffer-text character closest to that
position.
corner of the object described by @var{position}, as a cons cell
@w{@code{(@var{dx} . @var{dy})}}. If the @var{position} describes
buffer text, return the relative coordinates of the buffer-text character
closest to that position.
@end defun
@defun posn-object-width-height position
Return the pixel width and height of the object in @var{position} as a
cons cell @code{(@var{width} . @var{height})}. If the @var{position}
is a buffer position, return the size of the character at that position.
Return the pixel width and height of the object described by
@var{position}, as a cons cell @code{(@var{width} . @var{height})}.
If the @var{position} describes a buffer position, return the size of
the character at that position.
@end defun
@cindex timestamp of a mouse event