comparison doc/lispref/commands.texi @ 98751:a0e705c1e7f7

(Using Interactive, Interactive Codes): Document `^'. (Interactive Examples): Show an example of `^'. (Key Sequence Input): Document this-command-keys-shift-translated.

98750:3d5bcaefd8cf

@end group
@end smallexample

@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
If the first character in the string is @samp{*}, then an error is
signaled if the buffer is read-only.

@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
If the first character in the string is @samp{@@}, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

You can use @samp{*} and @samp{@@} together; the order does not matter.
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not @samp{*} or
@samp{@@}).

@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input

@item @@
Select the window mentioned in the first mouse event in the key
sequence that invoked this command.  Special.

@item a
A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
Completion, Prompt.

@item b

     @result{} foo1
@end group

@group
(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
    (interactive "p")       ;   @r{which is the numeric prefix.}
    (forward-word (* 2 n)))
     @result{} foo2
@end group

@group

@xref{Strings of Events}.
@end defun

@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
If an input character is upper-case (or has the shift modifier) and
has no key binding, but its lower-case equivalent has one, then
@code{read-key-sequence} converts the character to lower case.  Note
that @code{lookup-key} does not perform case conversion in this way.

The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
button-down events entirely.  It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence

98751:a0e705c1e7f7

@end group
@end smallexample

@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
If @samp{*} appears at the beginning of the string, then an error is
signaled if the buffer is read-only.

@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
If @samp{@@} appears at the beginning of the string, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

@cindex @samp{^} in @code{interactive}
@cindex shift-selection, and @code{interactive} spec
If @samp{^} appears at the beginning of the string, and if the command
was invoked through @dfn{shift-translation}, set the mark and activate
the region temporarily, or extend an already active region, before the
command is run.  If the command was invoked without shift-translation,
and the region is temporarily active, deactivate the region before the
command is run.  Shift-translation is controlled on the user level by
@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
Emacs Manual}.

You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
not matter.  Actual reading of arguments is controlled by the rest of
the prompt string (starting with the first character that is not
@samp{*}, @samp{@@}, or @samp{^}).

@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input

@item @@
Select the window mentioned in the first mouse event in the key
sequence that invoked this command.  Special.

@item ^
If the command was invoked through shift-translation, set the mark and
activate the region temporarily, or extend an already active region,
before the command is run.  If the command was invoked without
shift-translation, and the region is temporarily active, deactivate
the region before the command is run.  Special.

@item a
A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
Completion, Prompt.

@item b

     @result{} foo1
@end group

@group
(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
    (interactive "^p")      ;   @r{which is the numeric prefix.}
                            ; @r{under @code{shift-select-mode},}
                            ;   @r{will activate or extend region.}
    (forward-word (* 2 n)))
     @result{} foo2
@end group

@group

@xref{Strings of Events}.
@end defun

@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
@cindex shift-translation
If an input character is upper-case (or has the shift modifier) and
has no key binding, but its lower-case equivalent has one, then
@code{read-key-sequence} converts the character to lower case.  Note
that @code{lookup-key} does not perform case conversion in this way.

@vindex this-command-keys-shift-translated
When reading input results in such a @dfn{shift-translation}, Emacs
sets the variable @code{this-command-keys-shift-translated} to a
non-nil value.  Lisp programs can examine this variable if they need
to modify their behavior when invoked by shift-translated keys.  For
example, the function @code{handle-shift-selection} examines the value
of this variable to determine how to activate or deactivate the region
(@pxref{The Mark, handle-shift-selection}).

The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
button-down events entirely.  It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence