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