@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Command Loop
of @code{describe-function} will include similar information.
The value of the property can be: a string, which the byte-compiler
will use directly in its warning (it should end with a period, and not
-start with a capital, e.g. ``use @dots{} instead.''); @code{t}; any
+start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any
other symbol, which should be an alternative function to use in Lisp
code.
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt. This is done using
-@code{format} (@pxref{Formatting Strings}). For example, here is how
+@code{format-message} (@pxref{Formatting Strings}). For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:
@end defun
@menu
-* Keyboard Events:: Ordinary characters--keys with symbols on them.
-* Function Keys:: Function keys--keys with names, not symbols.
+* Keyboard Events:: Ordinary characters -- keys with symbols on them.
+* Function Keys:: Function keys -- keys with names, not symbols.
* Mouse Events:: Overview of mouse events.
* Click Events:: Pushing and releasing a mouse button.
* Drag Events:: Moving the mouse before releasing the button.
(the area above the handle), @code{below-handle} (the area below the
handle), @code{up} (the up arrow at one end of the scroll bar), or
@code{down} (the down arrow at one end of the scroll bar).
-@c The `top', `bottom', and `end-scroll' codes don't seem to be used.
+@c The 'top', 'bottom', and 'end-scroll' codes don't seem to be used.
@end table
single-click command has already run. It must produce the desired
results of a double click, starting from the results of a single click.
-This is convenient, if the meaning of a double click somehow ``builds
-on'' the meaning of a single click---which is recommended user interface
+This is convenient, if the meaning of a double click somehow builds
+on the meaning of a single click---which is recommended user interface
design practice for double clicks.
If you click a button, then press it down again and start moving the
@vindex mouse-wheel-up-event
@vindex mouse-wheel-down-event
-This kind of event is generated only on some kinds of systems. On some
+This kind of event is generated only on some kinds of systems. On some
systems, @code{mouse-4} and @code{mouse-5} are used instead. For
portable code, use the variables @code{mouse-wheel-up-event} and
@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
@end smallexample
The frame with input focus might not take up the entire screen, and
-the user might move the mouse outside the scope of the frame. Inside
+the user might move the mouse outside the scope of the frame. Inside
the @code{track-mouse} special form, that produces an event like this:
@smallexample
@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.
+@var{position} does not include actual position values; in that case
+@code{posn-col-row} can be used to get approximate values.
+
+Note that this function doesn't account for the visual width of
+characters on display, like the number of visual columns taken by a
+tab character or an image. If you need the coordinates in canonical
+character units, use @code{posn-col-row} instead.
@end defun
@defun posn-string position
@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 a buffer position, return the
-relative position in the character at that position.
+. @var{dy})}. If the @var{position} is on buffer text, return the
+relative position of the buffer-text character closest to that
+position.
@end defun
@defun posn-object-width-height position
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
-``prefix keys'', all of which are symbols: @code{header-line},
+prefix keys, all of which are symbols: @code{header-line},
@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
meanings for mouse clicks in special window parts by defining key
account, use the function @code{read-key}:
@defun read-key &optional prompt
-This function reads a single key. It is ``intermediate'' between
+This function reads a single key. It is intermediate between
@code{read-key-sequence} and @code{read-event}. Unlike the former, it
reads a single key, not a key sequence. Unlike the latter, it does
not return a raw event, but decodes and translates the user input
Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
modification.
-When using a window system, the program can ``press'' any of the
+When using a window system, the program can press any of the
modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
keys can be virtually pressed.
@node Event Input Misc
@subsection Miscellaneous Event Input Features
-This section describes how to ``peek ahead'' at events without using
+This section describes how to peek ahead at events without using
them up, how to check for pending input, and how to discard pending
input. See also the function @code{read-passwd} (@pxref{Reading a
Password}).
Events read from this list are not normally added to the current
command's key sequence (as returned by, e.g., @code{this-command-keys}),
as the events will already have been added once as they were read for
-the first time. An element of the form @code{(@code{t} . @var{event})}
+the first time. An element of the form @w{@code{(t . @var{event})}}
forces @var{event} to be added to the current command's key sequence.
@end defvar
binding is unwound at the end of a @code{let} form. At that time, if
@code{quit-flag} is still non-@code{nil}, the requested quit happens
immediately. This behavior is ideal when you wish to make sure that
-quitting does not happen within a ``critical section'' of the program.
+quitting does not happen within a critical section of the program.
@cindex @code{read-quoted-char} quitting
In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
change the major mode of the current buffer temporarily to a special
major mode, which should have a command to go back to the previous mode.
(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
-give the user different text to edit ``recursively'', create and select
+give the user different text to edit recursively, create and select
a new buffer in a special mode. In this mode, define a command to
complete the processing and go back to the previous buffer. (The
@kbd{m} command in Rmail does this.)