/[emacs]/emacs/lispref/commands.texi
ViewVC logotype

Diff of /emacs/lispref/commands.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.44 by eliz, Sun Nov 2 06:29:56 2003 UTC revision 1.45 by kfstorm, Sun Nov 23 00:59:23 2003 UTC
# Line 1119  binding of the key sequence. Line 1119  binding of the key sequence.
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
# Line 1155  describe events by their types; thus, if Line 1141  describe events by their types; thus, if
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
# Line 1629  a mouse button or motion event. Line 1659  a mouse button or motion event.
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
# Line 1650  position such events have. Line 1680  position such events have.
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
# Line 1667  cell @code{(@var{x} . @var{y})}. Line 1711  cell @code{(@var{x} . @var{y})}.
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

Legend:
Removed from v.1.44  
changed lines
  Added in v.1.45

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26