1119 |
@cindex mouse click event |
@cindex mouse click event |
1120 |
|
|
1121 |
When the user presses a mouse button and releases it at the same |
When the user presses a mouse button and releases it at the same |
1122 |
location, that generates a @dfn{click} event. Mouse click events have |
location, that generates a @dfn{click} event. All mouse click event |
1123 |
this form: |
share the same format: |
1124 |
|
|
1125 |
@example |
@example |
1126 |
(@var{event-type} |
(@var{event-type} @var{position} @var{click-count}) |
|
(@var{window} @var{buffer-pos} (@var{x} . @var{y}) |
|
|
@var{timestamp}) |
|
|
@var{click-count}) |
|
1127 |
@end example |
@end example |
1128 |
|
|
|
or, for clicks on strings in the mode line, header line or marginal |
|
|
areas: |
|
|
|
|
|
@example |
|
|
(@var{event-type} |
|
|
(@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos}) |
|
|
@var{click-count}) |
|
|
@end example |
|
|
|
|
|
Here is what the elements normally mean: |
|
|
|
|
1129 |
@table @asis |
@table @asis |
1130 |
@item @var{event-type} |
@item @var{event-type} |
1131 |
This is a symbol that indicates which mouse button was used. It is |
This is a symbol that indicates which mouse button was used. It is |
1141 |
@code{mouse-1}, that binding would apply to all events whose |
@code{mouse-1}, that binding would apply to all events whose |
1142 |
@var{event-type} is @code{mouse-1}. |
@var{event-type} is @code{mouse-1}. |
1143 |
|
|
1144 |
|
@item @var{position} |
1145 |
|
This is the position where the mouse click occurred. The actual |
1146 |
|
format of @var{position} depends on what part of a window was clicked |
1147 |
|
on. The various formats are described below. |
1148 |
|
|
1149 |
|
@item @var{click-count} |
1150 |
|
This is the number of rapid repeated presses so far of the same mouse |
1151 |
|
button. @xref{Repeat Events}. |
1152 |
|
@end table |
1153 |
|
|
1154 |
|
For mouse click events in the text area, mode line, header line, or in |
1155 |
|
the marginal areas, @var{position} has this form: |
1156 |
|
|
1157 |
|
@example |
1158 |
|
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} @var{object} @var{text-pos} (@var{col} . @var{row})) |
1159 |
|
@end example |
1160 |
|
|
1161 |
|
@table @asis |
1162 |
@item @var{window} |
@item @var{window} |
1163 |
This is the window in which the click occurred. |
This is the window in which the click occurred. |
1164 |
|
|
1165 |
|
@item @var{pos-or-area} |
1166 |
|
This is the buffer position of the character clicked on in the text |
1167 |
|
area, or if clicked outside the text area, it is the window area in |
1168 |
|
which the click occurred. It is one of the symbols @code{mode-line}, |
1169 |
|
@code{header-line}, @code{vertical-line}, @code{left-margin}, |
1170 |
|
@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. |
1171 |
|
|
1172 |
@item @var{x}, @var{y} |
@item @var{x}, @var{y} |
1173 |
These are the pixel-denominated coordinates of the click, relative to |
These are the pixel-denominated coordinates of the click, relative to |
1174 |
the top left corner of @var{window}, which is @code{(0 . 0)}. |
the top left corner of @var{window}, which is @code{(0 . 0)}. |
1175 |
|
For the mode or header line, @var{y} does not have meaningful data. |
1176 |
@item @var{buffer-pos} |
For the vertical line, @var{x} does not have meaningful data. |
|
This is the buffer position of the character clicked on. |
|
1177 |
|
|
1178 |
@item @var{timestamp} |
@item @var{timestamp} |
1179 |
This is the time at which the event occurred, in milliseconds. (Since |
This is the time at which the event occurred, in milliseconds. |
1180 |
this value wraps around the entire range of Emacs Lisp integers in about |
|
1181 |
five hours, it is useful only for relating the times of nearby |
@item @var{object} |
1182 |
events.) |
This is the object on which the click occurred. It is either nil (for |
1183 |
|
a click in a marginal area with no associated object, or it has the |
1184 |
|
form (@var{string} . @var{string-pos}). |
1185 |
|
|
1186 |
@item @var{string} |
@item @var{string} |
1187 |
This is the string on which the click occurred, including any |
This is the string on which the click occurred, including any |
1188 |
properties. |
properties. |
1189 |
|
|
1190 |
@item @var{string-pos} |
@item @var{string-pos} |
1191 |
This is the position in the string on which the click occurred, |
This is the position in the string on which the click occurred, |
1192 |
relevant if properties at the click need to be looked up. |
relevant if properties at the click need to be looked up. |
1193 |
|
|
1194 |
@item @var{click-count} |
@item @var{text-pos} |
1195 |
This is the number of rapid repeated presses so far of the same mouse |
For clicks on a marginal area or on a fringe, this is the buffer |
1196 |
button. @xref{Repeat Events}. |
position of the first visible character in the corresponding line in |
1197 |
|
the window. For other events, it is the current buffer position in |
1198 |
|
the window. |
1199 |
|
|
1200 |
|
@item @var{col}, @var{row} |
1201 |
|
These are the actual coordinates of the glyph under the @var{x}, |
1202 |
|
@var{y} position, possibly padded with default character width |
1203 |
|
glyphs if @var{x} is beyond the last glyph on the line. |
1204 |
@end table |
@end table |
1205 |
|
|
1206 |
The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat |
For mouse clicks on a scroll-bar, @var{position} has this form: |
1207 |
different when the event location is in a special part of the screen, |
|
1208 |
such as the mode line or a scroll bar. |
@example |
1209 |
|
(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) |
1210 |
If the location is in a scroll bar, then @var{buffer-pos} is the symbol |
@end example |
1211 |
@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair |
|
1212 |
@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion} |
@table @asis |
1213 |
. @var{whole})}, where @var{portion} is the distance of the click from |
@item @var{window} |
1214 |
the top or left end of the scroll bar, and @var{whole} is the length of |
This is the window whose scroll-bar was clicked on. |
1215 |
the entire scroll bar. |
|
1216 |
|
@item @var{area} |
1217 |
If the position is on a mode line, the vertical line separating |
This is the scroll bar where the click occurred. It is one of the |
1218 |
@var{window} from its neighbor to the right, or in a marginal area, |
symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. |
1219 |
then @var{buffer-pos} is the symbol @code{mode-line}, |
|
1220 |
@code{header-line}, @code{vertical-line}, @code{left-margin}, or |
@item @var{portion} |
1221 |
@code{right-margin}. For the mode line, @var{y} does not have |
This is the distance of the click from the top or left end of |
1222 |
meaningful data. For the vertical line, @var{x} does not have |
the scroll bar. |
1223 |
meaningful data. |
|
1224 |
|
@item @var{whole} |
1225 |
|
This is the length of the entire scroll bar. |
1226 |
|
|
1227 |
|
@item @var{timestamp} |
1228 |
|
This is the time at which the event occurred, in milliseconds. |
1229 |
|
|
1230 |
|
@item @var{part} |
1231 |
|
This is the part of the scroll-bar which was clicked on. It is one |
1232 |
|
of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, |
1233 |
|
@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. |
1234 |
|
@end table |
1235 |
|
|
1236 |
In one special case, @var{buffer-pos} is a list containing a symbol (one |
In one special case, @var{buffer-pos} is a list containing a symbol (one |
1237 |
of the symbols listed above) instead of just the symbol. This happens |
of the symbols listed above) instead of just the symbol. This happens |
1659 |
mouse-button event, as a list of this form: |
mouse-button event, as a list of this form: |
1660 |
|
|
1661 |
@example |
@example |
1662 |
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp}) |
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} @var{object} @var{text-pos} (@var{col} . @var{row})) |
1663 |
@end example |
@end example |
1664 |
|
|
1665 |
@defun event-start event |
@defun event-start event |
1680 |
@end defun |
@end defun |
1681 |
|
|
1682 |
@cindex mouse position list, accessing |
@cindex mouse position list, accessing |
1683 |
These five functions take a position list as described above, and |
These seven functions take a position list as described above, and |
1684 |
return various parts of it. |
return various parts of it. |
1685 |
|
|
1686 |
@defun posn-window position |
@defun posn-window position |
1687 |
Return the window that @var{position} is in. |
Return the window that @var{position} is in. |
1688 |
@end defun |
@end defun |
1689 |
|
|
1690 |
|
@defun posn-area position |
1691 |
|
Return the window area recorded in @var{position}. It returns nil |
1692 |
|
when the event occurred in the text area of the window; otherwise, it |
1693 |
|
is a symbol identifying the area in which the the event occurred. |
1694 |
|
@end defun |
1695 |
|
|
1696 |
@defun posn-point position |
@defun posn-point position |
1697 |
Return the buffer position in @var{position}. This is an integer. |
Return the buffer position in @var{position}. When the event occurred |
1698 |
|
in the text area of the window, in a marginal area, or on a fringe, |
1699 |
|
this is an integer specifying a buffer position. Otherwise, the value |
1700 |
|
is undefined. |
1701 |
|
@end defun |
1702 |
|
|
1703 |
|
@defun posn-timestamp |
1704 |
|
Return the timestamp in @var{position}. This is the time at which the |
1705 |
|
event occurred, in milliseconds. |
1706 |
@end defun |
@end defun |
1707 |
|
|
1708 |
@defun posn-x-y position |
@defun posn-x-y position |
1711 |
@end defun |
@end defun |
1712 |
|
|
1713 |
@defun posn-col-row position |
@defun posn-col-row position |
1714 |
Return the row and column (in units of characters) of @var{position}, as |
Return the row and column (in units of frame default characters) of |
1715 |
a cons cell @code{(@var{col} . @var{row})}. These are computed from the |
@var{position}, as a cons cell @code{(@var{col} . @var{row})}. These |
1716 |
@var{x} and @var{y} values actually found in @var{position}. |
are computed from the @var{x} and @var{y} values actually found in |
1717 |
|
@var{position}. |
1718 |
|
@end defun |
1719 |
|
|
1720 |
|
@defun posn-actual-col-row position |
1721 |
|
Return the actual row and column in @var{position}, as a cons cell |
1722 |
|
@code{(@var{col} . @var{row})}. The values are the actual row number |
1723 |
|
in the window, and the actual character number in that row. Return |
1724 |
|
nil if @var{position} does not include the actual positions; in that |
1725 |
|
case, @code{posn-col-row} can be used to get approximate values. |
1726 |
@end defun |
@end defun |
1727 |
|
|
1728 |
@cindex mouse event, timestamp |
@cindex mouse event, timestamp |