@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@node Using Interactive
@subsection Using @code{interactive}
+@cindex arguments, interactive entry
This section describes how to write the @code{interactive} form that
makes a Lisp function an interactively-callable command, and how to
examine a command's @code{interactive} form.
@defspec interactive arg-descriptor
-@cindex argument descriptors
This special form declares that the function in which it appears is a
command, and that it may therefore be called interactively (via
@kbd{M-x} or by entering a key sequence bound to it). The argument
or more arguments.
@item
-@cindex argument prompt
It may be a string; then its contents should consist of a code character
followed by a prompt (which some code characters use and some ignore).
The prompt ends either with the end of the string or with a newline.
command. Usually this form will call various functions to read input
from the user, most often through the minibuffer (@pxref{Minibuffers})
or directly from the keyboard (@pxref{Reading Input}).
-@cindex argument evaluation form
Providing point or the mark as an argument value is also common, but
if you do this @emph{and} read input (whether using the minibuffer or
Otherwise, the command is added only if it uses the minibuffer to read
an argument. @xref{Command History}.
-The argument @var{keys}, if given, specifies the sequence of events to
-supply if the command inquires which events were used to invoke it.
-If @var{keys} is omitted or @code{nil}, the return value of
-@code{this-command-keys} is used. @xref{Definition of this-command-keys}.
+The argument @var{keys}, if given, should be a vector which specifies
+the sequence of events to supply if the command inquires which events
+were used to invoke it. If @var{keys} is omitted or @code{nil}, the
+default is the return value of @code{this-command-keys-vector}.
+@xref{Definition of this-command-keys-vector}.
@end defun
@defun command-execute command &optional record-flag keys special
@end defvar
@defun this-command-keys
-@anchor{Definition of this-command-keys}
This function returns a string or vector containing the key sequence
that invoked the present command, plus any previous commands that
-generated the prefix argument for this command. However, if the
-command has called @code{read-key-sequence}, it returns the last read
-key sequence. @xref{Key Sequence Input}. The value is a string if
-all events in the sequence were characters that fit in a string.
-@xref{Input Events}.
+generated the prefix argument for this command. Any events read by the
+command using @code{read-event} without a timeout get tacked on to the end.
+
+However, if the command has called @code{read-key-sequence}, it
+returns the last read key sequence. @xref{Key Sequence Input}. The
+value is a string if all events in the sequence were characters that
+fit in a string. @xref{Input Events}.
@example
@group
@end defun
@defun this-command-keys-vector
+@anchor{Definition of this-command-keys-vector}
Like @code{this-command-keys}, except that it always returns the events
in a vector, so you don't need to deal with the complexities of storing
input events in a string (@pxref{Strings of Events}).
@node Adjusting Point
@section Adjusting Point After Commands
+@cindex adjusting point
+@cindex invisible/intangible text, and point
+@cindex @code{display} property, and point display
+@cindex @code{composition} property, and point display
It is not easy to display a value of point in the middle of a
sequence of text that has the @code{display}, @code{composition} or
@node Keyboard Events
@subsection Keyboard Events
+@cindex keyboard events
There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys. Ordinary keys correspond to characters; the
parameters are used to display the help-echo text are described in
@ref{Text help-echo}.
-@cindex @code{usr1-signal} event
-@cindex @code{usr2-signal} event
-@item usr1-signal
-@itemx usr2-signal
-These events are generated when the Emacs process receives the signals
-@code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data
-because signals do not carry additional information.
+@cindex @code{sigusr1} event
+@cindex @code{sigusr2} event
+@cindex user signals
+@item sigusr1
+@itemx sigusr2
+These events are generated when the Emacs process receives
+the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
+additional data because signals do not carry additional information.
+
+To catch a user signal, bind the corresponding event to an interactive
+command in the @code{special-event-map} (@pxref{Active Keymaps}).
+The command is called with no arguments, and the specific signal event is
+available in @code{last-input-event}. For example:
+
+@smallexample
+(defun sigusr-handler ()
+ (interactive)
+ (message "Caught signal %S" last-input-event))
+
+(define-key special-event-map [sigusr1] 'sigusr-handler)
+@end smallexample
+
+To test the signal handler, you can make Emacs send a signal to itself:
+
+@smallexample
+(signal-process (emacs-pid) 'sigusr1)
+@end smallexample
@end table
If one of these events arrives in the middle of a key sequence---that
-453816))
@end smallexample
+To handle a SIGUSR1 signal, define an interactive function, and
+bind it to the @code{signal usr1} event sequence:
+
+@smallexample
+(defun usr1-handler ()
+ (interactive)
+ (message "Got USR1 signal"))
+(global-set-key [signal usr1] 'usr1-handler)
+@end smallexample
+
@node Classifying Events
@subsection Classifying Events
@cindex event type
@node Accessing Events
@subsection Accessing Events
-@cindex mouse events, accessing the data
-@cindex accessing data of mouse events
+@cindex mouse events, data in
This section describes convenient functions for accessing the data in
a mouse button or motion event.
is a buffer position, return the size of the character at that position.
@end defun
-@cindex mouse event, timestamp
@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}. This is the time at which the
@node Reading Input
@section Reading Input
+@cindex read input
+@cindex keyboard input
The editor command loop reads key sequences using the function
@code{read-key-sequence}, which uses @code{read-event}. These and other
for example, @code{describe-key} uses it to read the key to describe.
@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
-@cindex key sequence
This function reads a key sequence and returns it as a string or
vector. It keeps reading events until it has accumulated a complete key
sequence; that is, enough to specify a non-prefix command using the
If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
for user input to arrive. Idle timers---those created with
-@code{run-with-idle-timer} (@pxref{Timers})---can run during this
+@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
period. However, if @var{seconds} is non-@code{nil}, the state of
idleness remains unchanged. If Emacs is non-idle when
@code{read-event} is called, it remains non-idle throughout the
Normally you add events to the front of this list, so that the events
most recently unread will be reread first.
+
+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})}
+forces @var{event} to be added to the current command's key sequence.
@end defvar
@defun listify-key-sequence key
@end defmac
@defun discard-input
-@cindex flush input
-@cindex discard input
-@cindex terminate keyboard macro
+@cindex flushing input
+@cindex discarding input
+@cindex keyboard macro, terminating
This function discards the contents of the terminal input buffer and
cancels any keyboard macro that might be in the process of definition.
It returns @code{nil}.
after they are read, and this is the way for the event's definition to
find the actual event.
-The events types @code{iconify-frame}, @code{make-frame-visible} and
-@code{delete-frame} are normally handled in this way. The keymap which
+The events types @code{iconify-frame}, @code{make-frame-visible},
+@code{delete-frame}, @code{drag-n-drop}, and user signals like
+@code{sigusr1} are normally handled in this way. The keymap which
defines how to handle special events---and which events are special---is
in the variable @code{special-event-map} (@pxref{Active Keymaps}).
@node Waiting
@section Waiting for Elapsed Time or Input
-@cindex pausing
@cindex waiting
The wait functions are designed to wait for a certain amount of time
case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
to quote a @kbd{C-g}.
-@cindex prevent quitting
+@cindex preventing quitting
You can prevent quitting for a portion of a Lisp function by binding
the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
editing. When called from a Lisp program, it enters a recursive editing
level.
- In the following example, the function @code{simple-rec} first
+If the current buffer is not the same as the selected window's buffer,
+@code{recursive-edit} saves and restores the current buffer. Otherwise,
+if you switch buffers, the buffer you switched to is current after
+@code{recursive-edit} returns.
+
+In the following example, the function @code{simple-rec} first
advances point one word, then enters a recursive edit, printing out a
message in the echo area. The user can then do any editing desired, and
then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.