@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@cindex interactive function
A Lisp function becomes a command when its body contains, at top
-level, a form that calls the special form @code{interactive}. This
+level, a form that calls the special form @code{interactive}, or if
+the function's symbol has an @code{interactive-form} property. This
form does nothing when actually executed, but its presence serves as a
flag to indicate that interactive calling is permitted. Its argument
controls the reading of arguments for an interactive call.
@code{interactive} form are executed, but at this time
@code{interactive} simply returns @code{nil} without even evaluating its
argument.
+
+@cindex @code{interactive-form}, function property
+An interactive form can be added to a function post-facto via the
+@code{interactive-form} property of the function's symbol.
+@xref{Symbol Plists}.
@end defspec
There are three possibilities for the argument @var{arg-descriptor}:
@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
-If the first character in the string is @samp{*}, then an error is
+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 the first character in the string is @samp{@@}, and if the key
+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.
-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{@@}).
+@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
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.
@group
(defun foo2 (n) ; @r{@code{foo2} takes one argument,}
- (interactive "p") ; @r{which is the numeric prefix.}
+ (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
@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
-The alias @code{last-command-char} exists for compatibility with
-Emacs version 18.
+The alias @code{last-command-char} is obsolete.
@end defvar
@c Emacs 19 feature
* Event Examples:: Examples of the lists for mouse events.
* Classifying Events:: Finding the modifier keys in an event symbol.
Event types.
-* Accessing Events:: Functions to extract info from events.
+* Accessing Mouse:: Functions to extract info from mouse events.
+* Accessing Scroll:: Functions to get info from scroll bar events.
* Strings of Events:: Special considerations for putting
keyboard character events in a string.
@end menu
latter as the symbol @code{tab}.
Most of the time, it's not useful to distinguish the two. So normally
-@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map
-@code{tab} into 9. Thus, a key binding for character code 9 (the
-character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
-symbols in this group. The function @code{read-char} likewise converts
-these events into characters.
+@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
+to map @code{tab} into 9. Thus, a key binding for character code 9
+(the character @kbd{C-i}) also applies to @code{tab}. Likewise for
+the other symbols in this group. The function @code{read-char}
+likewise converts these events into characters.
In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
@end example
@end defun
-@node Accessing Events
-@subsection Accessing Events
+@node Accessing Mouse
+@subsection Accessing Mouse Events
@cindex mouse events, data in
This section describes convenient functions for accessing the data in
the entire window area including scroll bars, margins and fringes.
@end defun
+@node Accessing Scroll
+@subsection Accessing Scroll Bar Events
+@cindex scroll bar events, data in
+
These functions are useful for decoding scroll bar events.
@defun scroll-bar-event-ratio event
@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-@code{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
@end defvar
@defvar keyboard-translate-table
-This variable is the translate table for keyboard characters. It lets
-you reshuffle the keys on the keyboard without changing any command
-bindings. Its value is normally a char-table, or else @code{nil}.
-(It can also be a string or vector, but this is considered obsolete.)
+This terminal-local variable is the translate table for keyboard
+characters. It lets you reshuffle the keys on the keyboard without
+changing any command bindings. Its value is normally a char-table, or
+else @code{nil}. (It can also be a string or vector, but this is
+considered obsolete.)
If @code{keyboard-translate-table} is a char-table
(@pxref{Char-Tables}), then each character read from the keyboard is
@end group
@end example
-The alias @code{last-input-char} exists for compatibility with
-Emacs version 18.
+The alias @code{last-input-char} is obsolete.
@end defvar
@defmac while-no-input body@dots{}