File: commands.texi

package info (click to toggle)
elisp-manual-ja 20-2.5-jp-4
links: PTS
area: main
in suites: sarge
size: 3,996 kB
ctags: 239
sloc: lisp: 2,837; perl: 182; makefile: 45; sh: 16
file content (4329 lines) | stat: -rw-r--r-- 197,647 bytes
parent folder | download | duplicates (2)
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@c @chapter Command Loop
@chapter $B%3%^%s%I%k!<%W(B
@c @cindex editor command loop
@c @cindex command loop
@cindex $B%(%G%#%?%3%^%s%I%k!<%W(B
@cindex $B%3%^%s%I%k!<%W(B

@c   When you run Emacs, it enters the @dfn{editor command loop} almost
@c immediately.  This loop reads key sequences, executes their definitions,
@c and displays the results.  In this chapter, we describe how these things
@c are done, and the subroutines that allow Lisp programs to do them.  
$BFI<T$,(BEmacs$B$r5/F0$9$k$H!"(BEmacs$B$O$[$\$?$@$A$K(B@dfn{$B%(%G%#%?%3%^%s%I%k!<%W(B}
$B!J(Beditor command loop$B!K$KF~$j$^$9!#(B
$B$3$N%k!<%W$O!"%-!<Ns$rFI$_<h$j!"$=$l$i$NDj5A$r<B9T$7!"7k2L$rI=<($7$^$9!#(B
$BK\>O$G$O!"$3$l$,$I$N$h$&$K9T$o$l$k$N$+!"$*$h$S!"(B
Lisp$B%W%m%0%i%`$+$i$3$l$r9T$&$?$a$N%5%V%k!<%F%#%s$K$D$$$F=R$Y$^$9!#(B

@menu
* Command Overview::    How the command loop reads commands.
* Defining Commands::   Specifying how a function should read arguments.
* Interactive Call::    Calling a command, so that it will read arguments.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Input Events::	What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Special Events::      Events processed immediately and individually.
* Waiting::             Waiting for user input or elapsed time.
* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
* Prefix Command Arguments::    How the commands to set prefix args work.
* Recursive Editing::   Entering a recursive edit,
                          and why you usually shouldn't.
* Disabling Commands::  How the command loop handles disabled commands.
* Command History::     How the command history is set up, and how accessed.
* Keyboard Macros::     How keyboard macros are implemented.
@end menu

@node Command Overview
@c @section Command Loop Overview
@section $B%3%^%s%I%k!<%W$N35MW(B

@c   The first thing the command loop must do is read a key sequence, which
@c is a sequence of events that translates into a command.  It does this by
@c calling the function @code{read-key-sequence}.  Your Lisp code can also
@c call this function (@pxref{Key Sequence Input}).  Lisp programs can also
@c do input at a lower level with @code{read-event} (@pxref{Reading One
@c Event}) or discard pending input with @code{discard-input}
@c (@pxref{Event Input Misc}).
$B%3%^%s%I%k!<%W$,$^$:;O$a$K9T$&$3$H$O%-!<Ns!"(B
$B$D$^$j!"%3%^%s%I$XJQ49$5$l$k%$%Y%s%HNs$rFI$`$3$H$G$9!#(B
$B$3$l$K$O4X?t(B@code{read-key-sequence}$B$r8F$S=P$7$^$9!#(B
$BFI<T$N(BLisp$B%3!<%I$G$b$3$N4X?t$r8F$S=P$;$^$9!J(B@pxref{Key Sequence Input}$B!K!#(B
Lisp$B%W%m%0%i%`$G$O!"(B@code{read-event}$B!J(B@pxref{Reading One Event}$B!K$G(B
$BDc%l%Y%k$NF~NO$r9T$C$?$j!"(B
@code{discard-input}$B!J(B@pxref{Event Input Misc}$B!K$G(B
$B=hM}BT$ACf$NF~NO$rGK4~$G$-$^$9!#(B

@c   The key sequence is translated into a command through the currently
@c active keymaps.  @xref{Key Lookup}, for information on how this is done.
@c The result should be a keyboard macro or an interactively callable
@c function.  If the key is @kbd{M-x}, then it reads the name of another
@c command, which it then calls.  This is done by the command
@c @code{execute-extended-command} (@pxref{Interactive Call}).
$B%-!<Ns$O8=:_3h@-$J%-!<%^%C%W$r2p$7$F%3%^%s%I$KJQ49$5$l$^$9!#(B
$B$3$N=hM}J}K!$K$D$$$F$O(B@xref{Key Lookup}$B!#(B
$B$3$N7k2L$O!"%-!<%\!<%I%^%/%m$G$"$k$+!"(B
$BBPOCE*$K8F$S=P$72DG=$J4X?t$G$"$k$O$:$G$9!#(B
$B%-!<$,(B@kbd{M-x}$B$G$"$k$H!"JL$N%3%^%s%I$NL>A0$rFI$_<h$j!"(B
$B$=$N%3%^%s%I$r8F$S=P$7$^$9!#(B
$B$3$l$O%3%^%s%I(B@code{execute-extended-command}$B!J(B@pxref{Interactive Call}$B!K$G(B
$B=hM}$5$l$^$9!#(B

@c   To execute a command requires first reading the arguments for it.
@c This is done by calling @code{command-execute} (@pxref{Interactive
@c Call}).  For commands written in Lisp, the @code{interactive}
@c specification says how to read the arguments.  This may use the prefix
@c argument (@pxref{Prefix Command Arguments}) or may read with prompting
@c in the minibuffer (@pxref{Minibuffers}).  For example, the command
@c @code{find-file} has an @code{interactive} specification which says to
@c read a file name using the minibuffer.  The command's function body does
@c not use the minibuffer; if you call this command from Lisp code as a
@c function, you must supply the file name string as an ordinary Lisp
@c function argument.
$B%3%^%s%I$r<B9T$9$k$K$O!"$^$:!"$=$N0z?t$rFI$`I,MW$,$"$j$^$9!#(B
$B$3$l$O!"(B@code{command-execute}$B!J(B@pxref{Interactive Call}$B!K$r8F$S=P$7$F(B
$B9T$$$^$9!#(B
Lisp$B$G=q$+$l$?%3%^%s%I$G$O!"(B
@code{interactive}$B;XDj$,0z?t$NFI$_J}$r;X<($7$^$9!#(B
$BA0CV0z?t!J(B@pxref{Prefix Command Arguments}$B!K$r;H$C$?$j!"(B
$B%W%m%s%W%H$rI=<($7$F%_%K%P%C%U%!!J(B@pxref{Minibuffers}$B!K$+$iFI$_$^$9!#(B
$B$?$H$($P!"%3%^%s%I(B@code{find-file}$B$K$O!"(B
$B%_%K%P%C%U%!$+$i%U%!%$%kL>$rFI$`$3$H$r;X<($7$?(B
@code{interactive}$B;XDj$,$"$j$^$9!#(B
$B%3%^%s%I$N4X?tK\BN$G$O%_%K%P%C%U%!$r;H$$$^$;$s!#(B
$B$3$N%3%^%s%I$r(BLisp$B%3!<%I$+$i4X?t$H$7$F8F$S=P$9>l9g!"(B
$BDL>o$N(BLisp$B4X?t$N0z?t$H$7$F%U%!%$%kL>J8;zNs$r;XDj$9$kI,MW$,$"$j$^$9!#(B

@c   If the command is a string or vector (i.e., a keyboard macro) then
@c @code{execute-kbd-macro} is used to execute it.  You can call this
@c function yourself (@pxref{Keyboard Macros}).
$B%3%^%s%I$,J8;zNs$d%Y%/%H%k!J$D$^$j!"%-!<%\!<%I%^%/%m!K$G$"$k>l9g!"(B
@code{execute-kbd-macro}$B$rMQ$$$F$=$l$i$r<B9T$7$^$9!#(B
$BFI<T<+?H$,$3$N4X?t$r8F$S=P$7$F$b$+$^$$$^$;$s!J(B@pxref{Keyboard Macros}$B!K!#(B

@c   To terminate the execution of a running command, type @kbd{C-g}.  This
@c character causes @dfn{quitting} (@pxref{Quitting}).
$BF0:nCf$N%3%^%s%I$N<B9T$r;_$a$k$K$O!"(B@kbd{C-g}$B$rBG$A$^$9!#(B
$B$3$NJ8;z$O(B@dfn{$BCfCG(B}$B!J(Bquitting$B!K$r0z$-5/$3$7$^$9!J(B@pxref{Quitting}$B!K!#(B

@defvar pre-command-hook
@c The editor command loop runs this normal hook before each command.  At
@c that time, @code{this-command} contains the command that is about to
@c run, and @code{last-command} describes the previous command.
@c @xref{Hooks}.
$B%(%G%#%?%3%^%s%I%k!<%W$O!"3F%3%^%s%I$N$^$($K$3$N%N!<%^%k%U%C%/$r<B9T$9$k!#(B
$B$=$N:]!"(B@code{this-command}$B$K$O$3$l$+$i<B9T$9$k%3%^%s%I$,J];}$5$l!"(B
@code{last-command}$B$K$OD>A0$N%3%^%s%I$,$"$k!#(B
@pxref{Hooks}$B!#(B
@end defvar

@defvar post-command-hook
@c The editor command loop runs this normal hook after each command
@c (including commands terminated prematurely by quitting or by errors),
@c and also when the command loop is first entered.  At that time,
@c @code{this-command} describes the command that just ran, and
@c @code{last-command} describes the command before that.  @xref{Hooks}.
$B%(%G%#%?%3%^%s%I%k!<%W$O!"(B
$B!JCfCG$d%(%i!<$N$?$a$K40N;$7$J$+$C$?%3%^%s%I$r4^$a$F!K(B
$B3F%3%^%s%I$N$"$H$K$3$N%N!<%^%k%U%C%/$r<B9T$9$k!#(B
$B=i$a$F%3%^%s%I%k!<%W$KF~$C$?$H$-$K$b<B9T$9$k!#(B
$B$=$N:]!"(B@code{this-command}$B$K$O<B9T$7=*$($?$P$+$j$N%3%^%s%I$,$"$j!"(B
@code{last-command}$B$K$O$=$NA0$N%3%^%s%I$,$"$k!#(B
@pxref{Hooks}$B!#(B
@end defvar

@c   Quitting is suppressed while running @code{pre-command-hook} and
@c @code{post-command-hook}.  If an error happens while executing one of
@c these hooks, it terminates execution of the hook, and clears the hook
@c variable to @code{nil} so as to prevent an infinite loop of errors.
@code{pre-command-hook}$B$d(B@code{post-command-hook}$B$N<B9TCf$O!"(B
$BCfCG$r6X;_$7$^$9!#(B
$B$3$l$i$N%U%C%/$N(B1$B$D$r<B9TCf$K%(%i!<$,5/$-$k$H!"(B
$B%(%i!<$NL58B%k!<%W$rKI$0$?$a$K!"(B
$B%U%C%/$N<B9T$r=*N;$7%U%C%/JQ?t$r(B@code{nil}$B$K$7$^$9!#(B

@node Defining Commands
@c @section Defining Commands
@section $B%3%^%s%I$NDj5A(B
@c @cindex defining commands
@c @cindex commands, defining
@c @cindex functions, making them interactive
@c @cindex interactive function
@cindex $B%3%^%s%I$NDj5A(B
@cindex $BDj5A!"%3%^%s%I(B
@cindex $B4X?t!"BPOCE*$K$9$k(B
@cindex $BBPOCE*4X?t(B

@c   A Lisp function becomes a command when its body contains, at top
@c level, a form that calls the special form @code{interactive}.  This
@c form does nothing when actually executed, but its presence serves as a
@c flag to indicate that interactive calling is permitted.  Its argument
@c controls the reading of arguments for an interactive call.
Lisp$B4X?t$NK\BN$K!"%9%Z%7%c%k%U%)!<%`(B@code{interactive}$B$r8F$S=P$9(B
$B%U%)!<%`$,%H%C%W%l%Y%k$K$"$k$H!"(BLisp$B4X?t$O%3%^%s%I$K$J$j$^$9!#(B
$B$3$N%U%)!<%`$O<B:]$K8F$S=P$5$l$F$b$J$K$b$7$^$;$s$,!"(B
$B$3$N%U%)!<%`$,$"$k$3$H$G!"BPOCE*$K8F$S=P$;$k$3$H$rI=$7$^$9!#(B
$B$=$N0z?t$,!"BPOCE*8F$S=P$7$K$*$1$k0z?t$NFI$_J}$r@)8f$7$^$9!#(B

@menu
* Using Interactive::     General rules for @code{interactive}.
* Interactive Codes::     The standard letter-codes for reading arguments
                             in various ways.
* Interactive Examples::  Examples of how to read interactive arguments.
@end menu

@node Using Interactive
@c @subsection Using @code{interactive}
@subsection @code{interactive}$B$N;H$$J}(B

@c   This section describes how to write the @code{interactive} form that
@c makes a Lisp function an interactively-callable command.
$BK\@a$G$O!"(BLisp$B4X?t$rBPOCE*$K8F$S=P$72DG=$J%3%^%s%I$K$9$k%U%)!<%`(B
@code{interactive}$B$N=q$-J}$K$D$$$F=R$Y$^$9!#(B

@defspec interactive arg-descriptor
@c @cindex argument descriptors
@cindex $B0z?t5-=R;R(B
@c This special form declares that the function in which it appears is a
@c command, and that it may therefore be called interactively (via
@c @kbd{M-x} or by entering a key sequence bound to it).  The argument
@c @var{arg-descriptor} declares how to compute the arguments to the
@c command when the command is called interactively.
$B$3$N%9%Z%7%c%k%U%)!<%`$O!"$3$l$r4^$`4X?t$,%3%^%s%I$G$"$j!"(B
$B!J(B@kbd{M-x}$B$dEv3:4X?t$K%P%$%s%I$7$?%-!<Ns$rF~NO$9$k$3$H$G!K(B
$BBPOCE*$K8F$S=P$;$k$3$H$r@k8@$9$k!#(B
$B0z?t(B@var{arg-descriptor}$B$O!"%3%^%s%I$rBPOCE*$K8F$S=P$7$?$H$-$K(B
$B%3%^%s%I$KBP$9$k0z?t$N7W;;J}K!$r@k8@$9$k!#(B

@c A command may be called from Lisp programs like any other function, but
@c then the caller supplies the arguments and @var{arg-descriptor} has no
@c effect.
$BB>$N4X?t$HF1MM$K!"%3%^%s%I$O(BLisp$B%W%m%0%i%`$+$i$b8F$S=P$;$k$,!"(B
$B$=$N>l9g!"8F$S=P$7B&$,0z?t$rEO$7!"(B@var{arg-descriptor}$B$K$O$J$s$N8z2L$b$J$$!#(B

@c The @code{interactive} form has its effect because the command loop
@c (actually, its subroutine @code{call-interactively}) scans through the
@c function definition looking for it, before calling the function.  Once
@c the function is called, all its body forms including the
@c @code{interactive} form are executed, but at this time
@c @code{interactive} simply returns @code{nil} without even evaluating its
@c argument.
$B%U%)!<%`(B@code{interactive}$B$,8z2L$rH/4x$9$k$N$O!"(B
$B%3%^%s%I%k!<%W!J<B:]$K$O%5%V%k!<%F%#%s(B@code{call-interactively}$B!K$,(B
$B4X?t$r8F$S=P$9$^$($K4X?tDj5A$rAv::$7$F$3$N%U%)!<%`$rC5$9$+$i$G$"$k!#(B
$B4X?t$,8F$S=P$5$l$k$H!"%U%)!<%`(B@code{interactive}$B$r4^$a$F(B
$B$=$NK\BN$N%U%)!<%`$,<B9T$5$l$k$,!"$=$N$H$-!"(B
@code{interactive}$B$O0z?t$rI>2A$;$:$KC1$K(B@code{nil}$B$rJV$9!#(B
@end defspec

@c There are three possibilities for the argument @var{arg-descriptor}:
$B0z?t(B@var{arg-descriptor}$B$K$O(B3$B$D$N2DG=@-$,$"$j$^$9!#(B

@itemize @bullet
@item
@c It may be omitted or @code{nil}; then the command is called with no
@c arguments.  This leads quickly to an error if the command requires one
@c or more arguments.
$B>JN,$9$k$+(B@code{nil}$B!#(B
$B$3$N>l9g!"%3%^%s%I$O0z?t$J$7$G8F$P$l$k!#(B
$B%3%^%s%I$,(B1$B$D0J>e$N0z?t$rI,MW$H$9$k>l9g!"$3$l$O$?$@$A$K%(%i!<$K$J$k!#(B

@item
@c It may be a Lisp expression that is not a string; then it should be a
@c form that is evaluated to get a list of arguments to pass to the
@c command.
@c @cindex argument evaluation form
$BJ8;zNs$G$O$J$$(BLisp$B<0!#(B
$B$3$N>l9g!"$=$l$O%U%)!<%`$G$"$j!"(B
$B%3%^%s%I$KEO$90z?t%j%9%H$rF@$k$?$a$KI>2A$5$l$k!#(B
@cindex $B0z?tI>2A%U%)!<%`(B

@c If this expression reads keyboard input (this includes using the
@c minibuffer), keep in mind that the integer value of point or the mark
@c before reading input may be incorrect after reading input.  This is
@c because the current buffer may be receiving subprocess output;
@c if subprocess output arrives while the command is waiting for input,
@c it could relocate point and the mark.
$B$3$N<0$,!J%_%K%P%C%U%!$r;H$&$3$H$r4^$a$F!K%-!<%\!<%IF~NO$rFI$`>l9g$K$O!"(B
$BF~NO$rFI$`$^$($N%]%$%s%H$N@0?tCM$d%^!<%/$O!"(B
$BF~NO$rFI$s$@$"$H$G$O@5$7$/$J$$2DG=@-$,$"$k$3$H$KN10U$9$k$3$H!#(B
$B%+%l%s%H%P%C%U%!$,%5%V%W%m%;%9$N=PNO$r<u$1<h$k2DG=@-$,$"$k$+$i$G$"$k!#(B
$B%3%^%s%I$,F~NO$rBT$C$F$$$k$"$$$@$K%5%V%W%m%;%9$N=PNO$,E~Ce$9$k$H!"(B
$B%]%$%s%H$d%^!<%/$r:FG[CV$9$k2DG=@-$,$"$k!#(B

@c Here's an example of what @emph{not} to do:
$B$7$F$O(B@emph{$B$$$1$J$$(B}$B$3$H$NNc$r<($9!#(B

@smallexample
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
@end smallexample

@noindent
@c Here's how to avoid the problem, by examining point and the mark only
@c after reading the keyboard input:
$B%-!<%\!<%IF~NO$rFI$_=*$($F$+$i%]%$%s%H$d%^!<%/$rD4$Y$k$3$H$G!"(B
$BLdBj$r2sHr$9$k!#(B

@smallexample
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
@end smallexample

@item
@c @cindex argument prompt
@cindex $B0z?t%W%m%s%W%H(B
@c It may be a string; then its contents should consist of a code character
@c followed by a prompt (which some code characters use and some ignore).
@c The prompt ends either with the end of the string or with a newline.
@c Here is a simple example:
$BJ8;zNs!#(B
$B$3$N>l9g!"$=$NFbMF$O!"%3!<%IJ8;z$H$=$l$KB3$/(B
$B!J%3!<%IJ8;z$K$h$C$F$O;H$C$?$jL5;k$9$k!K%W%m%s%W%H$+$i@.$k$3$H!#(B
$B%W%m%s%W%H$O!"J8;zNs$N=*$j$+2~9T$G=*$k!#(B
$B4JC1$JNc$r<($9!#(B

@smallexample
(interactive "bFrobnicate buffer: ")
@end smallexample

@noindent
@c The code letter @samp{b} says to read the name of an existing buffer,
@c with completion.  The buffer name is the sole argument passed to the
@c command.  The rest of the string is a prompt.
$B%3!<%IJ8;z(B@samp{b}$B$O!"Jd40$rMQ$$$F4{B8$N%P%C%U%!L>$rFI$`$3$H$r;X<($9$k!#(B
$B%P%C%U%!L>$O!"%3%^%s%I$KEO$5$l$kM#0l$N0z?t$G$"$k!#(B
$BJ8;zNs$N;D$j$O%W%m%s%W%H$G$"$k!#(B

@c If there is a newline character in the string, it terminates the prompt.
@c If the string does not end there, then the rest of the string should
@c contain another code character and prompt, specifying another argument.
@c You can specify any number of arguments in this way.
$BJ8;zNsFb$K2~9TJ8;z$,$"$k$H!"$=$l$O%W%m%s%W%H$r=*$($k!#(B
$B$=$NItJ,$GJ8;zNs$,=*$i$J$$$H$-$K$O!"(B
$BJ8;zNs$N;D$j$NItJ,$K$O!"JL$N0z?t$r;XDj$9$k%3!<%IJ8;z$d%W%m%s%W%H$,$"$k!#(B
$B$3$N$h$&$K$7$F!"2?8D$N0z?t$G$b;XDj$G$-$k!#(B

@c @c Emacs 19 feature
@c The prompt string can use @samp{%} to include previous argument values
@c (starting with the first argument) in the prompt.  This is done using
@c @code{format} (@pxref{Formatting Strings}).  For example, here is how
@c you could read the name of an existing buffer followed by a new name to
@c give to that buffer:
$B%W%m%s%W%H$NJ8;zNs$G$O!"%W%m%s%W%HFb$N!JBh(B1$B0z?t$+$i;O$^$k!K(B
$B$^$($N0z?tCM$r4^$a$k$?$a$K(B@samp{%}$B$r;H$($k!#(B
$B$3$l$O(B@code{format}$B!J(B@pxref{Formatting Strings}$B!K$rMQ$$$F9T$&!#(B
$B$?$H$($P!"4{B8%P%C%U%!$NL>A0$rFI$_!"(B
$BB3$1$F$=$N%P%C%U%!$KM?$($k?7$?$JL>A0$rFI$`$K$O$D$.$N$h$&$K$9$k!#(B

@smallexample
@group
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
@end group
@end smallexample

@c @cindex @samp{*} in interactive
@c @cindex read-only buffers in interactive
@cindex @samp{*}$B!"BPOC;XDj(B
@cindex $BFI$_=P$7@lMQ%P%C%U%!!"BPOC;XDj(B
@c If the first character in the string is @samp{*}, then an error is
@c signaled if the buffer is read-only.
$BJ8;zNs$N:G=i$NJ8;z$,(B@samp{*}$B$G$"$k>l9g!"(B
$B%P%C%U%!$,FI$_=P$7@lMQ$G$"$k$H%(%i!<$rDLCN$9$k!#(B

@c @cindex @samp{@@} in interactive
@cindex @samp{@@}$B!"BPOC;XDj(B
@c @c Emacs 19 feature
@c If the first character in the string is @samp{@@}, and if the key
@c sequence used to invoke the command includes any mouse events, then
@c the window associated with the first of those events is selected
@c before the command is run.
$BJ8;zNs$N:G=i$NJ8;z$,(B@samp{@@}$B$G$"$j!"(B
$B%3%^%s%I$r5/F0$7$?%-!<Ns$K%^%&%9%$%Y%s%H$,4^$^$l$k>l9g!"(B
$B%3%^%s%I$r<B9T$9$k$^$($K(B
$B$=$l$i$N%$%Y%s%H$N:G=i$N$b$N$K4XO"$7$?%&%#%s%I%&$rA*Br$9$k!#(B

@c You can use @samp{*} and @samp{@@} together; the order does not matter.
@c Actual reading of arguments is controlled by the rest of the prompt
@c string (starting with the first character that is not @samp{*} or
@c @samp{@@}).
@samp{*}$B$H(B@samp{@@}$B$OF1;~$K;H$(!"$=$N=g=x$O4X78$J$$!#(B
$B0z?t$N<B:]$NFI$_<h$j$O%W%m%s%W%H$N(B
$B!J(B@samp{*}$B$G$b(B@samp{@@}$B$G$b$J$$:G=i$NJ8;z$G;O$^$k!K;D$j$NItJ,$G@)8f$5$l$k!#(B
@end itemize

@node Interactive Codes
@comment  node-name,  next,  previous,  up
@c @subsection Code Characters for @code{interactive}
@subsection @code{interactive}$B$N%3!<%IJ8;z(B
@c @cindex interactive code description
@c @cindex description for interactive codes
@c @cindex codes, interactive, description of
@c @cindex characters for interactive codes
@cindex $BBPOC%3!<%I5-=R;R(B
@cindex $B5-=R;R!"BPOC;XDj$N%3!<%I(B
@cindex $B%3!<%I!"BPOC;XDj!"5-=R;R(B
@cindex $BJ8;z!"BPOC;XDj$N%3!<%I(B

@c   The code character descriptions below contain a number of key words,
@c defined here as follows:
$B0J2<$K=R$Y$k%3!<%IJ8;z$N@bL@$G$O!"(B
$B$D$.$KDj5A$9$k$$$/$D$+$N%-!<%o!<%I$r4^$_$^$9!#(B

@table @b
@c @item Completion
@item $B!VJd40!W(B
@c @cindex interactive completion
@cindex $BJd40!"BPOC;XDj(B
@c Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
@c completion because the argument is read using @code{completing-read}
@c (@pxref{Completion}).  @kbd{?} displays a list of possible completions.
$BJd40$r;H$($k!#(B
@code{completing-read}$B$r;H$C$F0z?t$rFI$`$?$a!"(B
@key{TAB}$B!"(B@key{SPC}$B!"(B@key{RET}$B$OL>A0$rJd40$9$k(B
$B!J(B@pxref{Completion}$B!K!#(B
@kbd{?}$B$OJd408uJd$N%j%9%H$rI=<($9$k!#(B

@c @item Existing
@item $B!V4{B8!W(B
@c Require the name of an existing object.  An invalid name is not
@c accepted; the commands to exit the minibuffer do not exit if the current
@c input is not valid.
$B4{B8%*%V%8%'%/%H$NL>A0$rI,MW$H$9$k!#(B
$BIT@5$JL>A0$O<u$1IU$1$J$$!#(B
$B8=:_$NF~NO$,@5$7$/$J$$$H%_%K%P%C%U%!$+$iH4$1$k%3%^%s%I$OF0:n$7$J$$!#(B

@c @item Default
@item $B!V%G%U%)%k%H!W(B
@c @cindex default argument string
@cindex $B%G%U%)%k%H0z?tJ8;zNs(B
@c A default value of some sort is used if the user enters no text in the
@c minibuffer.  The default depends on the code character.
$B%_%K%P%C%U%!$K%f!<%6!<$,$J$K$b%F%-%9%H$rF~NO$7$J$$$H$-$K(B
$B;H$o$l$k$J$s$i$+$N%G%U%)%k%HCM!#(B
$B%G%U%)%k%H$O%3!<%IJ8;z$K0MB8$9$k!#(B

@c @item No I/O
@item $B!VF~=PNO$J$7!W(B
@c This code letter computes an argument without reading any input.
@c Therefore, it does not use a prompt string, and any prompt string you
@c supply is ignored.
$B$3$N%3!<%IJ8;z$O!"F~NO$r$^$C$?$/FI$^$:$K0z?t$r7W;;$9$k!#(B
$B$7$?$,$C$F!"%W%m%s%W%HJ8;zNs$r;H$o$:!"(B
$BFI<T$,;XDj$7$?%W%m%s%W%HJ8;zNs$OL5;k$9$k!#(B

@c Even though the code letter doesn't use a prompt string, you must follow
@c it with a newline if it is not the last code character in the string.
$B%3!<%IJ8;z$O%W%m%s%W%HJ8;zNs$r;H$o$J$$$,!"(B
$B$3$NJ8;z$,J8;zNs$N:G8e$NJ8;z$G$J$$>l9g$K$O2~9T$rB3$1$k$3$H!#(B

@c @item Prompt
@item $B!V%W%m%s%W%H!W(B
@c A prompt immediately follows the code character.  The prompt ends either
@c with the end of the string or with a newline.
$B%3!<%IJ8;z$ND>8e$K%W%m%s%W%H$,B3$/!#(B
$B%W%m%s%W%H$OJ8;zNs$N=*$j$+2~9T$G=*$k!#(B

@c @item Special
@item $B!V%9%Z%7%c%k!W(B
@c This code character is meaningful only at the beginning of the
@c interactive string, and it does not look for a prompt or a newline.
@c It is a single, isolated character.
$B$3$N%3!<%IJ8;z$O!"BPOC;XDjJ8;zNs$N@hF,$G$N$_0UL#$r;}$A!"(B
$B%W%m%s%W%H$d2~9T$rI,MW$H$7$J$$!#(B
$B$3$l$O(B1$B$D$N8IN)$7$?J8;z$G$"$k!#(B
@end table

@c @cindex reading interactive arguments
@cindex $BFI$_<h$j!"BPOC0z?t(B
@c   Here are the code character descriptions for use with @code{interactive}:
$B0J2<$K!"(B@code{interactive}$B$K;H$&%3!<%IJ8;z$r@bL@$7$^$9!#(B

@table @samp
@item *
@c Signal an error if the current buffer is read-only.  Special.
$B%+%l%s%H%P%C%U%!$,FI$_=P$7@lMQ$G$"$k$H%(%i!<$rDLCN$9$k!#(B
$B!V%9%Z%7%c%k!W!#(B

@item @@
@c Select the window mentioned in the first mouse event in the key
@c sequence that invoked this command.  Special.
$B$3$N%3%^%s%I$r5/F0$7$?%-!<Ns$N:G=i$N%^%&%9%$%Y%s%H$,I=$9%&%#%s%I%&$rA*Br$9$k!#(B
$B!V%9%Z%7%c%k!W!#(B

@item a
@c A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
@c Completion, Prompt.
$B4X?tL>!J$D$^$j!"(B@code{fboundp}$B$rK~$?$9%7%s%\%k!K!#(B
$B!V4{B8!W!"!VJd40!W!"!V%W%m%s%W%H!W!#(B

@item b
@c The name of an existing buffer.  By default, uses the name of the
@c current buffer (@pxref{Buffers}).  Existing, Completion, Default,
@c Prompt.
$B4{B8%P%C%U%!$NL>A0!#(B
$B%G%U%)%k%H$G$O!"%+%l%s%H%P%C%U%!!J(B@pxref{Buffers}$B!K$NL>A0$r;H$&!#(B
$B!V4{B8!W!"!VJd40!W!"!V%G%U%)%k%H!W!"!V%W%m%s%W%H!W!#(B

@item B
@c A buffer name.  The buffer need not exist.  By default, uses the name of
@c a recently used buffer other than the current buffer.  Completion,
@c Default, Prompt.
$B%P%C%U%!L>!#(B
$B%P%C%U%!$,4{B8$G$"$kI,MW$O$J$$!#(B
$B%G%U%)%k%H$G$O!"%+%l%s%H%P%C%U%!0J30$N:G6a;H$C$?%P%C%U%!$NL>A0$r;H$&!#(B
$B!VJd40!W!"!V%G%U%)%k%H!W!"!V%W%m%s%W%H!W!#(B

@item c
@c A character.  The cursor does not move into the echo area.  Prompt.
$BJ8;z!#(B
$B%+!<%=%k$O%(%3!<NN0h$K$O0\F0$7$J$$!#(B
$B!V%W%m%s%W%H!W!#(B

@item C
@c A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
@c Completion, Prompt.
$B%3%^%s%IL>!J$D$^$j!"(B@code{commandp}$B$rK~$?$9%7%s%\%k!K!#(B
$B!V4{B8!W!"!VJd40!W!"!V%W%m%s%W%H!W!#(B

@item d
@c @cindex position argument
@cindex $B0LCV0z?t(B
@c The position of point, as an integer (@pxref{Point}).  No I/O.
$B@0?t$H$7$F$N%]%$%s%H0LCV!J(B@pxref{Point}$B!K!#(B
$B!VF~=PNO$J$7!W!#(B

@item D
@c A directory name.  The default is the current default directory of the
@c current buffer, @code{default-directory} (@pxref{System Environment}).
@c Existing, Completion, Default, Prompt.
$B%G%#%l%/%H%jL>!#(B
$B%G%U%)%k%H$O!"%+%l%s%H%P%C%U%!$N%+%l%s%H%G%U%)%k%H%G%#%l%/%H%j(B
@code{default-directory}$B!J(B@pxref{System Environment}$B!K!#(B
$B!V4{B8!W!"!VJd40!W!"!V%G%U%)%k%H!W!"!V%W%m%s%W%H!W!#(B

@item e
@c The first or next mouse event in the key sequence that invoked the command.
@c More precisely, @samp{e} gets events that are lists, so you can look at
@c the data in the lists.  @xref{Input Events}.  No I/O.
$B%3%^%s%I$r5/F0$7$?%-!<Ns$N:G=i$d$D$.$N%^%&%9%$%Y%s%H!#(B
$B$h$j@53N$K$O!"(B@samp{e}$B$O%j%9%H$G$"$k%$%Y%s%H$r<hF@$9$k$N$G!"(B
$BFI<T$O%j%9%HFb$N%G!<%?$rD4$Y$i$l$k!#(B
@pxref{Input Events}$B!#(B
$B!VF~=PNO$J$7!W!#(B

@c You can use @samp{e} more than once in a single command's interactive
@c specification.  If the key sequence that invoked the command has
@c @var{n} events that are lists, the @var{n}th @samp{e} provides the
@c @var{n}th such event.  Events that are not lists, such as function keys
@c and @sc{ASCII} characters, do not count where @samp{e} is concerned.
1$B$D$N%3%^%s%I$NBPOC;XDj$GJ#?t2s(B@samp{e}$B$r;H$($k!#(B
$B%3%^%s%I$r5/F0$7$?%-!<Ns$,(B@var{n}$B8D$N%j%9%H$G$"$k%$%Y%s%H$G$"$k>l9g!"(B
@var{n}$BHVL\$N(B@samp{e}$B$O!"(B@var{n}$BHVL\$N$=$N$h$&$J%$%Y%s%H$rM?$($k!#(B
@samp{e}$B$G$O!"(B
$B%U%!%s%/%7%g%s%-!<$d(B@sc{ASCII}$BJ8;z$J$I$N%j%9%H$G$J$$%$%Y%s%H$O?t$($J$$!#(B

@item f
@c A file name of an existing file (@pxref{File Names}).  The default
@c directory is @code{default-directory}.  Existing, Completion, Default,
@c Prompt.
$B4{B8%U%!%$%k$NL>A0!J(B@pxref{File Names}$B!K!#(B
$B%G%U%)%k%H%G%#%l%/%H%j$O(B@code{default-directory}$B!#(B
$B!V4{B8!W!"!VJd40!W!"!V%G%U%)%k%H!W!"!V%W%m%s%W%H!W!#(B

@item F
@c A file name.  The file need not exist.  Completion, Default, Prompt.
$B%U%!%$%kL>!#(B
$B%U%!%$%k$,4{B8$G$"$kI,MW$O$J$$!#(B
$B!VJd40!W!"!V%G%U%)%k%H!W!"!V%W%m%s%W%H!W!#(B

@item i
@c An irrelevant argument.  This code always supplies @code{nil} as
@c the argument's value.  No I/O.
$BL54X78$J0z?t!#(B
$B$3$N%3!<%I$O!"0z?t$NCM$K$D$M$K(B@code{nil}$B$rM?$($k!#(B
$B!VF~=PNO$J$7!W!#(B

@item k
@c A key sequence (@pxref{Keymap Terminology}).  This keeps reading events
@c until a command (or undefined command) is found in the current key
@c maps.  The key sequence argument is represented as a string or vector.
@c The cursor does not move into the echo area.  Prompt.
$B%-!<Ns!J(B@pxref{Keymap Terminology}$B!K!#(B
$B8=:_$N%-!<%^%C%W$K$*$$$F%3%^%s%I$,$_$D$+$k!J$"$k$$$OL$Dj5A%3%^%s%I!K$^$G(B
$B%$%Y%s%H$rFI$_B3$1$k!#(B
$B%-!<Ns0z?t$O!"J8;zNs$+%Y%/%H%k$H$7$FI=8=$5$l$k!#(B
$B%+!<%=%k$O%(%3!<NN0h$K$O0\F0$7$J$$!#(B
$B!V%W%m%s%W%H!W!#(B

@c This kind of input is used by commands such as @code{describe-key} and
@c @code{global-set-key}.
$B$3$N<o$NF~NO$O!"(B@code{describe-key}$B$d(B@code{global-set-key}$B$J$I$N(B
$B%3%^%s%I$G;H$o$l$k!#(B

@item K
@c A key sequence, whose definition you intend to change.  This works like
@c @samp{k}, except that it suppresses, for the last input event in the key
@c sequence, the conversions that are normally used (when necessary) to
@c convert an undefined key into a defined one.
$B%-!<Ns$G$"$j!"FI<T$,$=$NDj5A$rJQ99$9$k$3$H$r0U?^$7$F$$$k!#(B
$B$3$l$O(B@samp{k}$B$HF1MM$KF0:n$9$k$,!"(B
$B%-!<Ns$N:G8e$NF~NO%$%Y%s%H$KBP$7$F$O!"(B
$BL$Dj5A%-!<$rDj5A:Q$_$N$b$N$KJQ49$9$k$?$a$K!JI,MW$J$H$-$K!KIaDL;H$o$l$k(B
$BJQ49=hM}$rM^@)$9$k!#(B

@item m
@c @cindex marker argument
@cindex $B%^!<%/0z?t(B
@c The position of the mark, as an integer.  No I/O.
$B@0?t$H$7$F$N%^!<%/0LCV!#(B
$B!VF~=PNO$J$7!W!#(B

@item M
@c Arbitrary text, read in the minibuffer using the current buffer's input
@c method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
@c Emacs Manual}).  Prompt.
$B%+%l%s%H%P%C%U%!$NF~NOJ}<0$rMQ$$$F%_%K%P%C%U%!$GFI$s$@G$0U$N%F%-%9%H!#(B
$BJ8;zNs$H$7$FJV$9(B
$B!J(B@pxref{Input Methods,, $BF~NOJ}<0(B, emacs, GNU Emacs $B%^%K%e%"%k(B}$B!K!#(B
$B!V%W%m%s%W%H!W!#(B

@item n
@c A number read with the minibuffer.  If the input is not a number, the
@c user is asked to try again.  The prefix argument, if any, is not used.
@c Prompt.
$B%_%K%P%C%U%!$GFI$s$@?t!#(B
$BF~NO$,?t$G$J$$$H!"%f!<%6!<$K:FF~NO$rB%$9!#(B
$B$b$7A0CV0z?t$,$"$C$F$b$=$l$O;H$o$J$$!#(B
$B!V%W%m%s%W%H!W!#(B

@item N
@c @cindex raw prefix argument usage
@cindex $B@8$NA0CV0z?t$N;H$$J}(B
@c The numeric prefix argument; but if there is no prefix argument, read a
@c number as with @kbd{n}.  Requires a number.  @xref{Prefix Command
@c Arguments}.  Prompt.
$B?tCMA0CV0z?t!#(B
$BA0CV0z?t$,$J$1$l$P!"(B@kbd{n}$B$G?t$rFI$`!#(B
$B?t$rI,MW$H$9$k!#(B
@pxref{Prefix Command Arguments}$B!#(B
$B!V%W%m%s%W%H!W!#(B

@item p
@c @cindex numeric prefix argument usage
@cindex $B?tCMA0CV0z?t$N;H$$J}(B
@c The numeric prefix argument.  (Note that this @samp{p} is lower case.)
@c No I/O.
$B?tCMA0CV0z?t!#(B
$B!J$3$N(B@samp{p}$B$O>.J8;z!#!K(B
$B!VF~=PNO$J$7!W!#(B

@item P
@c The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
@c I/O.
$B@8$NA0CV0z?t!#(B
$B!J$3$N(B@samp{P}$B$OBgJ8;z!#!K(B
$B!VF~=PNO$J$7!W!#(B

@item r
@c @cindex region argument
@cindex $B%j!<%8%g%s0z?t(B
@c Point and the mark, as two numeric arguments, smallest first.  This is
@c the only code letter that specifies two successive arguments rather than
@c one.  No I/O.
2$B$D$N?tCM0z?t$H$7$F$N%]%$%s%H$H%^!<%/!#(B
$B>.$5$$$[$&$,@h$K$/$k!#(B
$B$3$l$O!"(B1$B$D$G$O$J$/(B2$B$D$NO"B3$7$?0z?t$r;XDj$9$kM#0l$N%3!<%IJ8;z!#(B
$B!VF~=PNO$J$7!W!#(B

@item s
@c Arbitrary text, read in the minibuffer and returned as a string
@c (@pxref{Text from Minibuffer}).  Terminate the input with either
@c @kbd{C-j} or @key{RET}.  (@kbd{C-q} may be used to include either of
@c these characters in the input.)  Prompt.
$B%_%K%P%C%U%!$GFI$s$@G$0U$N%F%-%9%H!#(B
$BJ8;zNs$H$7$FJV$9!J(B@pxref{Text from Minibuffer}$B!K!#(B
@kbd{C-j}$B$+(B@key{RET}$B$GF~NO$r=*$($k!#(B
$B!J$3$l$i$NJ8;z$rF~NO$K4^$a$k$K$O(B@kbd{C-q}$B$r;H$&!#!K(B
$B!V%W%m%s%W%H!W!#(B

@item S
@c An interned symbol whose name is read in the minibuffer.  Any whitespace
@c character terminates the input.  (Use @kbd{C-q} to include whitespace in
@c the string.)  Other characters that normally terminate a symbol (e.g.,
@c parentheses and brackets) do not do so here.  Prompt.
$B%_%K%P%C%U%!$GFI$s$@L>A0$r%$%s%?!<%s$7$?%7%s%\%k!#(B
$BGrJ8;z$GF~NO$r=*$($k!#(B
$B!JJ8;zNs$KGrJ8;z$r4^$a$k$K$O(B@kbd{C-q}$B$r;H$&!#!K(B
$B!J4]3g8L$d3Q3g8L$J$I$N!KDL>o$O%7%s%\%k$r=*$($kB>$NJ8;z$O!"(B
$B$3$3$G$O%7%s%\%k$r=*C<$7$J$$!#(B
$B!V%W%m%s%W%H!W!#(B

@item v
@c A variable declared to be a user option (i.e., satisfying the predicate
@c @code{user-variable-p}).  @xref{High-Level Completion}.  Existing,
@c Completion, Prompt.
$B%f!<%6!<%*%W%7%g%s$H@k8@$5$l$?JQ?t(B
$B!J$D$^$j!"=R8l(B@code{user-variable-p}$B$rK~$?$9!K!#(B
@pxref{High-Level Completion}$B!#(B
$B!V4{B8!W!"!VJd40!W!"!V%W%m%s%W%H!W!#(B

@item x
@c A Lisp object, specified with its read syntax, terminated with a
@c @kbd{C-j} or @key{RET}.  The object is not evaluated.  @xref{Object from
@c Minibuffer}.  Prompt.
$BF~NO9=J8$GI=$5$l$?(BLisp$B%*%V%8%'%/%H!#(B
@kbd{C-j}$B$+(B@key{RET}$B$G=*$($k!#(B
$B%*%V%8%'%/%H$OI>2A$7$J$$!#(B
@pxref{Object from Minibuffer}$B!#(B
$B!V%W%m%s%W%H!W!#(B

@item X
@c @cindex evaluated expression argument
@cindex $BI>2A:Q$_$N<00z?t(B
@c A Lisp form is read as with @kbd{x}, but then evaluated so that its
@c value becomes the argument for the command.  Prompt.
@kbd{x}$B$N$h$&$K(BLisp$B%U%)!<%`$rFI$`$,!"I>2A$7$=$NCM$,%3%^%s%I$N0z?t$K$J$k!#(B
$B!V%W%m%s%W%H!W!#(B

@item z
@c A coding system name (a symbol).  If the user enters null input, the
@c argument value is @code{nil}.  @xref{Coding Systems}.  Completion,
@c Existing, Prompt.
$B%3!<%G%#%s%0%7%9%F%`L>!J%7%s%\%k!K!#(B
$B%f!<%6!<$NF~NO$,6u$G$"$k$H!"0z?t$NCM$O(B@code{nil}$B!#(B
@pxref{Coding Systems}$B!#(B
$B!VJd40!W!"!V4{B8!W!"!V%W%m%s%W%H!W!#(B

@item Z
@c A coding system name (a symbol)---but only if this command has a prefix
@c argument.  With no prefix argument, @samp{Z} provides @code{nil} as the
@c argument value.  Completion, Existing, Prompt.
$B$3$N%3%^%s%I$KA0CV0z?t$r;XDj$7$?>l9g$K$N$_!"(B
$B%3!<%G%#%s%0%7%9%F%`L>!J%7%s%\%k!K!#(B
$BA0CV0z?t$,$J$$$H!"(B@samp{Z}$B$O0z?t$NCM$K(B@code{nil}$B$rM?$($k!#(B
$B!VJd40!W!"!V4{B8!W!"!V%W%m%s%W%H!W!#(B
@end table

@node Interactive Examples
@comment  node-name,  next,  previous,  up
@c @subsection Examples of Using @code{interactive}
@subsection @code{interactive}$B$N;HMQNc(B
@c @cindex examples of using @code{interactive}
@c @cindex @code{interactive}, examples of using 
@cindex @code{interactive}$B$N;HMQNc(B
@cindex $BNc!"(B@code{interactive}

@c   Here are some examples of @code{interactive}:
$B$3$3$G$O(B@code{interactive}$B$NNc$r<($7$^$9!#(B

@example
@group
@c (defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
@c     (interactive)           ;   @r{just moves forward two words.}
(defun foo1 ()              ; @r{@code{foo1}$B$O0z?t$J$7(B}
    (interactive)           ; @r{2$BC18lJ,@h$X?J$a$k(B}
    (forward-word 2))
     @result{} foo1
@end group

@group
@c (defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
@c     (interactive "p")       ;   @r{which is the numeric prefix.}
(defun foo2 (n)             ; @r{@code{foo2}$B$O(B1$B0z?t(B}
    (interactive "p")       ; @r{$B?tCMA0CV0z?t(B}
    (forward-word (* 2 n)))
     @result{} foo2
@end group

@group
@c (defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
@c     (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
(defun foo3 (n)             ; @r{@code{foo3}$B$O(B1$B0z?t(B}
    (interactive "nCount:") ; @r{$B%_%K%P%C%U%!$GFI$`(B}
    (forward-word (* 2 n)))
     @result{} foo3
@end group

@group
(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."
@end group
    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     @result{} three-b
@group
(three-b "*scratch*" "declarations.texi" "*mail*")
     @result{} nil
@end group
@end example

@node Interactive Call
@c @section Interactive Call
@section $BBPOCE*8F$S=P$7(B
@c @cindex interactive call
@cindex $BBPOCE*8F$S=P$7(B

@c   After the command loop has translated a key sequence into a command it
@c invokes that command using the function @code{command-execute}.  If the
@c command is a function, @code{command-execute} calls
@c @code{call-interactively}, which reads the arguments and calls the
@c command.  You can also call these functions yourself.
$B%3%^%s%I%k!<%W$G$O!"%-!<Ns$r%3%^%s%I$XJQ49$7=*$($k$H!"(B
$B4X?t(B@code{command-execute}$B$rMQ$$$F$=$N%3%^%s%I$r5/F0$7$^$9!#(B
$B%3%^%s%I$,4X?t$G$"$l$P!"(B@code{command-execute}$B$O0z?t$rFI$_<h$j!"(B
$B%3%^%s%I$r8F$S=P$9(B@code{call-interactively}$B$r8F$S$^$9!#(B
$BFI<T<+?H$,$3$l$i$N4X?t$r8F$S=P$7$F$b$+$^$$$^$;$s!#(B

@defun commandp object
@c Returns @code{t} if @var{object} is suitable for calling interactively;
@c that is, if @var{object} is a command.  Otherwise, returns @code{nil}.  
@var{object}$B$,BPOCE*8F$S=P$7$KE,$7$F$$$l$P!"(B
$B$D$^$j!"(B@var{object}$B$,%3%^%s%I$G$"$l$P(B@code{t}$B$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@c The interactively callable objects include strings and vectors (treated
@c as keyboard macros), lambda expressions that contain a top-level call to
@c @code{interactive}, byte-code function objects made from such lambda
@c expressions, autoload objects that are declared as interactive
@c (non-@code{nil} fourth argument to @code{autoload}), and some of the
@c primitive functions.
$BBPOCE*8F$S=P$7$,2DG=$J%*%V%8%'%/%H$K$O!"(B
$B!J%-!<%\!<%I%^%/%m$H$7$F07$o$l$k!KJ8;zNs$d%Y%/%H%k!"(B
$B%H%C%W%l%Y%k$G(B@code{interactive}$B$r8F$S=P$7$F$$$k%i%`%@<0!"(B
$B$=$N$h$&$J%i%`%@<0$r%3%s%Q%$%k$7$?%P%$%H%3!<%I4X?t%*%V%8%'%/%H!"(B
$BBPOCE*!J(B@code{autoload}$B$N(B4$BHVL\$N0z?t$,(B@code{nil}$B0J30!K(B
$B$H@k8@$5$l$?<+F0%m!<%I%*%V%8%'%/%H!"(B
$B0lIt$N4pK\4X?t$,4^$^$l$k!#(B

@c A symbol satisfies @code{commandp} if its function definition satisfies
@c @code{commandp}.
$B%7%s%\%k$N4X?tDj5A$,(B@code{commandp}$B$rK~$?$;$P!"(B
$B%7%s%\%k$b(B@code{commandp}$B$rK~$?$9!#(B

@c Keys and keymaps are not commands.  Rather, they are used to look up
@c commands (@pxref{Keymaps}).
$B%-!<$d%-!<%^%C%W$O%3%^%s%I$G$O$J$$!#(B
$B$=$l$i$O%3%^%s%I$rC5$9$?$a$K;H$o$l$k!J(B@pxref{Keymaps}$B!K!#(B

@c See @code{documentation} in @ref{Accessing Documentation}, for a
@c realistic example of using @code{commandp}.
@code{commandp}$B$N<BMQE*$J;HMQNc$K$D$$$F$O!"(B
@ref{Accessing Documentation}$B$N(B@code{documentation}$B$r;2>H!#(B
@end defun

@defun call-interactively command &optional record-flag keys
@c This function calls the interactively callable function @var{command},
@c reading arguments according to its interactive calling specifications.
@c An error is signaled if @var{command} is not a function or if it cannot
@c be called interactively (i.e., is not a command).  Note that keyboard
@c macros (strings and vectors) are not accepted, even though they are
@c considered commands, because they are not functions.
$B$3$N4X?t$O!"BPOCE*8F$S=P$72DG=$J4X?t(B@var{command}$B$r(B
$B$=$NBPOC;XDj$K=>$C$F0z?t$rFI$_<h$j8F$S=P$9!#(B
@var{command}$B$,4X?t$G$J$+$C$?$j!"(B
$BBPOCE*$K8F$S=P$;$J$$!J$D$^$j!"%3%^%s%I$G$J$$!K>l9g$K$O!"(B
$B%(%i!<$rDLCN$9$k!#(B
$B%-!<%\!<%I%^%/%m!JJ8;zNs$d%Y%/%H%k!K$O%3%^%s%I$H$_$J$9$,!"(B
$B$=$l$i$O4X?t$G$J$$$?$a!"$3$N4X?t$O%-!<%\!<%I%^%/%m$r<u$1IU$1$J$$!#(B

@c @cindex record command history
@cindex $B%3%^%s%IMzNr$N5-O?(B
@c If @var{record-flag} is non-@code{nil}, then this command and its
@c arguments are unconditionally added to the list @code{command-history}.
@c Otherwise, the command is added only if it uses the minibuffer to read
@c an argument.  @xref{Command History}.
@var{record-flag}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%3%^%s%I$H$=$N0z?t$rL5>r7o$K%j%9%H(B@code{command-history}$B$KDI2C$9$k!#(B
$B$5$b$J$1$l$P!"0z?t$rFI$`$?$a$K(B
$B%3%^%s%I$,%_%K%P%C%U%!$r;H$C$?>l9g$K$N$_DI2C$9$k!#(B
@pxref{Command History}$B!#(B

@c The argument @var{keys}, if given, specifies the sequence of events to
@c supply if the command inquires which events were used to invoke it.
$B$b$70z?t(B@var{keys}$B$r;XDj$9$k$H!"%3%^%s%I$,$=$l$r5/F0$7$?%$%Y%s%H$r(B
$BLd$$9g$o$;$?$H$-$KM?$($k%$%Y%s%HNs$r;XDj$9$k!#(B
@end defun

@defun command-execute command &optional record-flag keys
@c @cindex keyboard macro execution
@cindex $B%-!<%\!<%I%^%/%m$N<B9T(B
@c This function executes @var{command}.  The argument @var{command} must
@c satisfy the @code{commandp} predicate; i.e., it must be an interactively
@c callable function or a keyboard macro.
$B$3$N4X?t$O(B@var{command}$B$r<B9T$9$k!#(B
$B0z?t(B@var{command}$B$O(B@code{commandp}$B$rK~$?$9$3$H!#(B
$B$D$^$j!"BPOCE*8F$S=P$72DG=$J4X?t$+%-!<%\!<%I%^%/%m$G$"$k$3$H!#(B

@c A string or vector as @var{command} is executed with
@c @code{execute-kbd-macro}.  A function is passed to
@c @code{call-interactively}, along with the optional @var{record-flag}.
@code{command}$B$,J8;zNs$d%Y%/%H%k$G$"$k$H!"(B
@code{execute-kbd-macro}$B$G<B9T$5$l$k!#(B
$B4X?t$G$"$k$H!">JN,2DG=$J(B@var{record-flag}$B$H$H$b$K4X?t$r(B
@code{call-interactively}$B$KEO$9!#(B

@c A symbol is handled by using its function definition in its place.  A
@c symbol with an @code{autoload} definition counts as a command if it was
@c declared to stand for an interactively callable function.  Such a
@c definition is handled by loading the specified library and then
@c rechecking the definition of the symbol.
$B%7%s%\%k$O!"$=$N4X?tDj5A$r;H$C$F=hM}$9$k!#(B
@code{autoload}$B$GDj5A$5$l$?%7%s%\%k$O!"(B
$BBPOCE*8F$S=P$72DG=$J4X?t$H@k8@$5$l$F$$$l$P%3%^%s%I$H$_$J$9!#(B
$B$=$N$h$&$JDj5A$G$O!";XDj$5$l$?%i%$%V%i%j$r%m!<%I$7$F$+$i(B
$B%7%s%\%k$NDj5A$r:F8!::$7$F=hM}$9$k!#(B

@c The argument @var{keys}, if given, specifies the sequence of events to
@c supply if the command inquires which events were used to invoke it.
$B$b$70z?t(B@var{keys}$B$r;XDj$9$k$H!"%3%^%s%I$,$=$l$r5/F0$7$?%$%Y%s%H$r(B
$BLd$$9g$o$;$?$H$-$KM?$($k%$%Y%s%HNs$r;XDj$9$k!#(B
@end defun

@c @deffn Command execute-extended-command prefix-argument
@deffn $B%3%^%s%I(B execute-extended-command prefix-argument
@c @cindex read command name
@cindex $B%3%^%s%IL>$NFI$_<h$j(B
@c This function reads a command name from the minibuffer using
@c @code{completing-read} (@pxref{Completion}).  Then it uses
@c @code{command-execute} to call the specified command.  Whatever that
@c command returns becomes the value of @code{execute-extended-command}.
$B$3$N4X?t$O(B@code{completing-read}$B!J(B@pxref{Completion}$B!K$r;H$C$F(B
$B%_%K%P%C%U%!$G%3%^%s%IL>$rFI$`!#(B
$B$=$7$F(B@code{command-execute}$B$r;H$C$F;XDj$5$l$?%3%^%s%I$r<B9T$9$k!#(B
$B%3%^%s%I$,JV$7$?CM$,(B@code{execute-extended-command}$B$NCM$K$J$k!#(B

@c @cindex execute with prefix argument
@cindex $BA0CV0z?tIU$-$N<B9T(B
@c If the command asks for a prefix argument, it receives the value
@c @var{prefix-argument}.  If @code{execute-extended-command} is called
@c interactively, the current raw prefix argument is used for
@c @var{prefix-argument}, and thus passed on to whatever command is run.
$B%3%^%s%I$,A0CV0z?t$rI,MW$H$9$k>l9g!"(B@var{prefix-argument}$B$NCM$r<u$1<h$k!#(B
@code{execute-extended-command}$B$,BPOCE*$K8F$P$l$?>l9g!"(B
$B8=:_$N@8$NA0CV0z?t$,(B@var{prefix-argument}$B$H$7$F;H$o$l!"(B
$B$=$l$,<B9T$9$k%3%^%s%I$XEO$5$l$k!#(B

@c !!! Should this be @kindex?
@cindex @kbd{M-x}
@c @code{execute-extended-command} is the normal definition of @kbd{M-x},
@c so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
@c to take the prompt from the events used to invoke
@c @code{execute-extended-command}, but that is painful to implement.)  A
@c description of the value of the prefix argument, if any, also becomes
@c part of the prompt.
@code{execute-extended-command}$B$ODL>o(B@kbd{M-x}$B$KDj5AIU$1$i$l!"(B
$B$=$N$?$a!"%W%m%s%W%H$H$7$FJ8;zNs(B@w{@samp{M-x }}$B$r;H$&!#(B
$B!J(B@code{execute-extended-command}$B$r5/F0$9$k$?$a$K;H$o$l$?(B
$B%$%Y%s%H$r%W%m%s%W%H$K$9$k$Y$-$G$"$k$,!"(B
$B$=$l$r<BAu$9$k$N$O<j4V$,$+$+$k!#!K(B
$B$b$7A0CV0z?t$r;XDj$9$k$H!"$=$NFbMF$b%W%m%s%W%H$N0lIt$K$J$k!#(B

@example
@group
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     @result{} t
@end group
@end example
@end deffn

@defun interactive-p
@c This function returns @code{t} if the containing function (the one whose
@c code includes the call to @code{interactive-p}) was called
@c interactively, with the function @code{call-interactively}.  (It makes
@c no difference whether @code{call-interactively} was called from Lisp or
@c directly from the editor command loop.)  If the containing function was
@c called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
@c it was not called interactively.
$B$3$N4X?t$O!"$3$l!J(B@code{interactive-p}$B$N8F$S=P$7!K$r4^$s$@4X?t$,(B
@code{call-interactively}$B$GBPOCE*$K8F$S=P$5$l$k$H(B@code{t}$B$rJV$9!#(B
$B!J(BLisp$B$+$i(B@code{call-interactively}$B$,8F$S=P$5$l$F$b!"(B
$B%(%G%#%?%3%^%s%I%k!<%W$,D>@\8F$S=P$7$F$b0c$$$O$J$$!#!K(B
$B$3$l$r4^$s$@4X?t$,(BLisp$B$NI>2A!J$"$k$$$O(B@code{apply}$B$d(B@code{funcall}$B!K$G(B
$B8F$S=P$5$l$?>l9g$O!"BPOCE*8F$S=P$7$G$O$J$$!#(B
@end defun

@c   The most common use of @code{interactive-p} is for deciding whether to
@c print an informative message.  As a special exception,
@c @code{interactive-p} returns @code{nil} whenever a keyboard macro is
@c being run.  This is to suppress the informative messages and speed
@c execution of the macro.
@code{interactive-p}$B$N$b$C$H$b0lHLE*$JMQES$O!"(B
$B>pJs%a%C%;!<%8$rI=<($9$k$+$I$&$+7h$a$k$3$H$G$9!#(B
$BFCJL$JNc30$H$7$F!"%-!<%\!<%I%^%/%m$r<B9TCf$K$O$$$D$G$b!"(B
@code{interactive-p}$B$O(B@code{nil}$B$rJV$7$^$9!#(B
$B$3$l$O>pJs%a%C%;!<%8$r>J$$$F%^%/%m$N<B9T$rB.$/$9$k$?$a$G$9!#(B

@c   For example:
$B$D$.$N$h$&$K;H$$$^$9!#(B

@example
@group
(defun foo ()
  (interactive)
  (when (interactive-p)
    (message "foo")))
     @result{} foo
@end group

@group
(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     @result{} bar
@end group

@group
@c ;; @r{Type @kbd{M-x foo}.}
;; @r{@kbd{M-x foo}$B$HBG$D(B}
     @print{} foo
@end group

@group
@c ;; @r{Type @kbd{M-x bar}.}
@c ;; @r{This does not print anything.}
;; @r{@kbd{M-x bar}$B$HBG$D(B}
;; @r{$B$3$l$O$J$K$bI=<($7$J$$(B}
@end group

@group
foobar
     @result{} (nil t)
@end group
@end example

@c   The other way to do this sort of job is to make the command take an
@c argument @code{print-message} which should be non-@code{nil} in an
@c interactive call, and use the @code{interactive} spec to make sure it is
@c non-@code{nil}.  Here's how:
$B$3$N<o$N$3$H$r9T$&JL$NJ}K!$O!"%3%^%s%I$r(B
$BBPOCE*8F$S=P$7$G$O(B@code{nil}$B0J30$NCM$K$J$k0z?t(B@code{print-message}$B$r(B
$B<h$k$h$&$K$7!"$=$N0z?t$,(B@code{nil}$B0J30$K$J$k$h$&$J(B@code{interactive}$B;XDj$r(B
$B;H$&$3$H$G$9!#(B
$B$D$.$N$h$&$K$7$^$9!#(B

@example
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
@end example

@c   The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@samp{p}$B$GM?$($i$l$k?tCMA0CV0z?t$O$1$C$7$F(B@code{nil}$B$K$J$j$^$;$s!#(B

@node Command Loop Info
@comment  node-name,  next,  previous,  up
@c @section Information from the Command Loop
@section $B%3%^%s%I%k!<%W$+$i$N>pJs(B

@c The editor command loop sets several Lisp variables to keep status
@c records for itself and for commands that are run.  
$B%(%G%#%?%3%^%s%I%k!<%W$O!"<+?H$d<B9TCf$N%3%^%s%I$N$?$a$K(B
$B>uBV5-O?$r?t8D$N(BLisp$BJQ?t$K@_Dj$7$^$9!#(B

@defvar last-command
@c This variable records the name of the previous command executed by the
@c command loop (the one before the current command).  Normally the value
@c is a symbol with a function definition, but this is not guaranteed.
$B$3$NJQ?t$O!"%3%^%s%I%k!<%W$,!J8=:_$N%3%^%s%I$N!K$^$($K<B9T$7$?%3%^%s%I$N(B
$BL>A0$r5-O?$9$k!#(B
$BDL>o!"$3$NCM$O4X?tDj5A$r;}$D%7%s%\%k$G$"$k$,!"J]>Z$O$7$J$$!#(B

@c The value is copied from @code{this-command} when a command returns to
@c the command loop, except when the command has specified a prefix
@c argument for the following command.
$B%3%^%s%I$,8eB3$N%3%^%s%I$KBP$9$kA0CV0z?t$r;XDj$9$k>l9g$r=|$$$F!"(B
$B%3%^%s%I$+$i%3%^%s%I%k!<%W$XLa$k$H(B@code{this-command}$B$+$iCM$r%3%T!<$9$k!#(B

@c This variable is always local to the current terminal and cannot be
@c buffer-local.  @xref{Multiple Displays}.
$B$3$NJQ?t$O8=:_$NC<Kv$KBP$7$F$D$M$K%m!<%+%k$G$"$j!"(B
$B%P%C%U%!$KBP$7$F%m!<%+%k$K$O$J$i$J$$!#(B
@pxref{Multiple Displays}$B!#(B
@end defvar

@tindex real-last-command
@defvar real-last-command
@c This variable is set up by Emacs just like @code{last-command},
@c but never altered by Lisp programs.
@code{last-command}$B$HF1MM$K(BEmacs$B$,$3$NJQ?t$K@_Dj$9$k$,!"(B
Lisp$B%W%m%0%i%`$G$O$1$C$7$FJQ99$7$J$$!#(B
@end defvar

@defvar this-command
@c @cindex current command
@cindex $B8=:_$N%3%^%s%I(B
@c This variable records the name of the command now being executed by
@c the editor command loop.  Like @code{last-command}, it is normally a symbol
@c with a function definition.
$B$3$NJQ?t$O!"%(%G%#%?%3%^%s%I%k!<%W$,(B
$B$$$^<B9T$7$F$$$k%3%^%s%I$NL>A0$r5-O?$9$k!#(B
@code{last-command}$B$HF1MM$K!"DL>o$O4X?tDj5A$r;}$D%7%s%\%k$G$"$k!#(B

@c The command loop sets this variable just before running a command, and
@c copies its value into @code{last-command} when the command finishes
@c (unless the command specified a prefix argument for the following
@c command).
$B%3%^%s%I%k!<%W$O!"%3%^%s%I$r<B9T$9$kD>A0$K$3$NJQ?t$K@_Dj$7!"(B
$B%3%^%s%I$,=*N;$9$k$H!J%3%^%s%I$,8eB3$N%3%^%s%I$KBP$9$k(B
$BA0CV0z?t$r;XDj$9$k>l9g$r=|$$$F!K(B
$B$3$NCM$r(B@code{last-command}$B$K%3%T!<$9$k!#(B

@c @cindex kill command repetition
@cindex $B%-%k%3%^%s%I$N7+$jJV$7(B
@c Some commands set this variable during their execution, as a flag for
@c whatever command runs next.  In particular, the functions for killing text
@c set @code{this-command} to @code{kill-region} so that any kill commands
@c immediately following will know to append the killed text to the
@c previous kill.
$B8eB3$N%3%^%s%I$KBP$9$k%U%i%0$H$7$F(B
$B<B9TCf$K$3$NJQ?t$K@_Dj$9$k%3%^%s%I$b$"$k!#(B
$BFC$K!"%F%-%9%H$r%-%k$9$k4X?t72$O(B@code{this-command}$B$K(B@code{kill-region}$B$r(B
$B@_Dj$7$F!"D>8e$KB3$/%-%k%3%^%s%I$G$O(B
$B%-%k$7$?%F%-%9%H$r$^$($N%-%k$KDI2C$9$k$h$&$K$9$k!#(B
@end defvar

@c If you do not want a particular command to be recognized as the previous
@c command in the case where it got an error, you must code that command to
@c prevent this.  One way is to set @code{this-command} to @code{t} at the
@c beginning of the command, and set @code{this-command} back to its proper
@c value at the end, like this:
$BFCDj$N%3%^%s%I$,%(%i!<$r5/$3$7$?>l9g$K(B
$BD>A0$N%3%^%s%I$H$OG'<1$5$l$?$/$J$$>l9g$K$O!"(B
$BFI<T$O$=$N%3%^%s%I$,$=$l$rKI$0$h$&$K=q$/I,MW$,$"$j$^$9!#(B
1$B$D$NJ}K!$O!"0J2<$K<($9$h$&$K!"(B
$B%3%^%s%I$N;O$a$G(B@code{this-command}$B$K(B@code{t}$B$r@_Dj$7!"(B
$B%3%^%s%I$N=*$j$G(B@code{this-command}$B$K@5$7$$CM$rLa$7$^$9!#(B

@example
(defun foo (args@dots{})
  (interactive @dots{})
  (let ((old-this-command this-command))
    (setq this-command t)
    @r{@dots{}do the work@dots{}}
    (setq this-command old-this-command)))
@end example

@noindent
@c We do not bind @code{this-command} with @code{let} because that would
@c restore the old value in case of error---a feature of @code{let} which
@c in this case does precisely what we want to avoid.
@code{let}$B$G(B@code{this-command}$B$rB+G{$7$^$;$s!#(B
$B$H$$$&$N$O!"%(%i!<$,$"$k$H(B@code{let}$B$O8E$$CM$rI|85$9$k$+$i$G$9!#(B
$B$3$l$3$=$,$3$3$G$OHr$1$?$$(B@code{let}$B$N5!G=$G$9!#(B

@defun this-command-keys
@c This function returns a string or vector containing the key sequence
@c that invoked the present command, plus any previous commands that
@c generated the prefix argument for this command.  The value is a string
@c if all those events were characters.  @xref{Input Events}.
$B$3$N4X?t$O!"8=:_$N%3%^%s%I$KBP$7$FD>A0$N%3%^%s%I$,@8@.$7$?A0CV0z?t$r4^$a$F!"(B
$B8=:_$N%3%^%s%I$r5/F0$7$?%-!<Ns$r4^$s$@J8;zNs$+%Y%/%H%k$rJV$9!#(B
$B$9$Y$F$N%$%Y%s%H$,J8;z$G$"$l$P!"CM$OJ8;zNs$G$"$k!#(B
@pxref{Input Events}$B!#(B

@example
@group
(this-command-keys)
@c ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
;; @r{@kbd{C-u C-x C-e}$B$r;H$C$F$3$N<0$rI>2A$9$k(B}
     @result{} "^U^X^E"
@end group
@end example
@end defun

@defun this-command-keys-vector
@c Like @code{this-command-keys}, except that it always returns
@c the events in a vector, so you do never need to deal with the complexities
@c of storing input events in a string (@pxref{Strings of Events}).
@code{this-command-keys}$B$HF1MM$@$,!"$D$M$K%Y%/%H%k$G%$%Y%s%H$rJV$9$?$a!"(B
$BJ8;zNs$KF~NO%$%Y%s%H$rJ];}$9$k:]$NJ#;($5$r07$&I,MW$,$J$$(B
$B!J(B@pxref{Strings of Events}$B!K!#(B
@end defun

@defvar last-nonmenu-event
@c This variable holds the last input event read as part of a key sequence,
@c not counting events resulting from mouse menus.
$B$3$NJQ?t$O!"%^%&%9%a%K%e!<$K$h$k%$%Y%s%H$r9MN8$;$:$K!"(B
$B%-!<Ns$H$7$FFI$s$@:G8e$NF~NO%$%Y%s%H$rJ];}$9$k!#(B

@c One use of this variable is for telling @code{x-popup-menu} where to pop
@c up a menu.  It is also used internally by @code{y-or-n-p}
@c (@pxref{Yes-or-No Queries}).
$B$3$NJQ?t$N(B1$B$D$NMQES$O!"(B
$B%a%K%e!<$r%]%C%W%"%C%W$9$k0LCV$r(B@code{x-popup-menu}$B$K;X<($9$k$3$H$G$"$k!#(B
@code{y-or-n-p}$B!J(B@pxref{Yes-or-No Queries}$B!K$bFbItE*$K;H$C$F$$$k!#(B
@end defvar

@defvar last-command-event
@defvarx last-command-char
@c This variable is set to the last input event that was read by the
@c command loop as part of a command.  The principal use of this variable
@c is in @code{self-insert-command}, which uses it to decide which
@c character to insert.
$B$3$NJQ?t$K$O!"%3%^%s%I$N0lIt$H$7$F%3%^%s%I%k!<%W$,(B
$BFI$s$@:G8e$NF~NO%$%Y%s%H$,@_Dj$5$l$k!#(B
$B$3$NJQ?t$N<g$JMQES$O!"$I$NJ8;z$rA^F~$9$Y$-$+$r7hDj$9$k$?$a$K(B
@code{self-insert-command}$B$,;H$&$3$H$G$"$k!#(B

@example
@group
last-command-event
@c ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
;; @r{@kbd{C-u C-x C-e}$B$r;H$C$F$3$N<0$rI>2A$9$k(B}
     @result{} 5
@end group
@end example

@noindent
@c The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
@kbd{C-e}$B$N(B@sc{ASCII}$B%3!<%I$O(B5$B$J$N$G!"CM$O(B5$B$G$"$k!#(B

@c The alias @code{last-command-char} exists for compatibility with
@c Emacs version 18.
Emacs 18$BHG$H$N8_49@-$N$?$a$KJLL>(B@code{last-command-char}$B$,$"$k!#(B
@end defvar

@c Emacs 19 feature
@defvar last-event-frame
@c This variable records which frame the last input event was directed to.
@c Usually this is the frame that was selected when the event was
@c generated, but if that frame has redirected input focus to another
@c frame, the value is the frame to which the event was redirected.
@c @xref{Input Focus}.
$B$3$NJQ?t$O!":G8e$NF~NO%$%Y%s%H$r?6$j8~$1$?%U%l!<%`$r5-O?$9$k!#(B
$BDL>o$3$l$O!"%$%Y%s%H$,@8@.$5$l$?$H$-$KA*Br$5$l$F$$$?%U%l!<%`$G$"$k$,!"(B
$B$=$N%U%l!<%`$,F~NO%U%)!<%+%9$rJL$N%U%l!<%`$K?6$j8~$1$F$$$k$H!"(B
$B$3$NCM$O%$%Y%s%H$r?6$j8~$1$?@h$N%U%l!<%`$G$"$k!#(B
@pxref{Input Focus}$B!#(B
@end defvar

@node Input Events
@c @section Input Events
@section $BF~NO%$%Y%s%H(B
@c @cindex events
@c @cindex input events
@cindex $B%$%Y%s%H(B
@cindex $BF~NO%$%Y%s%H(B

@c The Emacs command loop reads a sequence of @dfn{input events} that
@c represent keyboard or mouse activity.  The events for keyboard activity
@c are characters or symbols; mouse events are always lists.  This section
@c describes the representation and meaning of input events in detail.
Emacs$B$N%3%^%s%I%k!<%W$O!"%-!<%\!<%I$d%^%&%9$N%f!<%6!<$NA`:n$rI=$9(B
@dfn{$BF~NO%$%Y%s%H(B}$B!J(Binput event$B!KNs$rFI$_$^$9!#(B
$B%-!<%\!<%IA`:n$KBP$9$k%$%Y%s%H$O!"J8;z$+%7%s%\%k$G$9!#(B
$B%^%&%9%$%Y%s%H$O$D$M$K%j%9%H$G$9!#(B
$BK\@a$G$O!"F~NO%$%Y%s%H$NI=8=J}K!$d$=$N0UL#$r>\$7$/@bL@$7$^$9!#(B

@defun eventp object
@c This function returns non-@code{nil} if @var{object} is an input event
@c or event type.
$B$3$N4X?t$O!"(B@var{object}$B$,F~NO%$%Y%s%H$G$"$k$+%$%Y%s%H7?$G$"$k$H(B
@code{nil}$B0J30$rJV$9!#(B

@c Note that any symbol might be used as an event or an event type.
@c @code{eventp} cannot distinguish whether a symbol is intended by Lisp
@c code to be used as an event.  Instead, it distinguishes whether the
@c symbol has actually been used in an event that has been read as input in
@c the current Emacs session.  If a symbol has not yet been so used,
@c @code{eventp} returns @code{nil}.
$BG$0U$N%7%s%\%k$,%$%Y%s%H$d%$%Y%s%H7?$H$7$F;H$o$l$k$3$H$KCm0U!#(B
@code{eventp}$B$O!"(BLisp$B$N%W%m%0%i%`%3!<%I$,%7%s%\%k$r(B
$B%$%Y%s%H$H$7$F;H$&$+$I$&$+6hJL$G$-$J$$!#(B
$B$=$N$+$o$j$K!"%7%s%\%k$,!"(BEmacs$B$N8=:_$N%;%C%7%g%s$K$*$$$FF~NO$H$7$FFI$^$l$?(B
$B%$%Y%s%H$K;H$o$l$?$3$H$,$"$k$+$I$&$+$r6hJL$9$k!#(B
$B%7%s%\%k$,$=$N$h$&$K;H$o$l$?$3$H$,$J$1$l$P!"(B
@code{eventp}$B$O(B@code{nil}$B$rJV$9!#(B
@end defun

@menu
* 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.
* Button-Down Events::		A button was pushed and not yet released.
* Repeat Events::               Double and triple click (or drag, or down).
* Motion Events::		Just moving the mouse, not pushing a button.
* Focus Events::		Moving the mouse between frames.
* Misc Events::                 Other events window systems can generate.
* 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.
* Strings of Events::           Special considerations for putting
				  keyboard character events in a string.
@end menu

@node Keyboard Events
@c @subsection Keyboard Events
@subsection $B%-!<%\!<%I%$%Y%s%H(B

@c There are two kinds of input you can get from the keyboard: ordinary
@c keys, and function keys.  Ordinary keys correspond to characters; the
@c events they generate are represented in Lisp as characters.  The event
@c type of a character event is the character itself (an integer); see
@c @ref{Classifying Events}.
$B%-!<%\!<%I$+$i$O(B2$B<oN`$NF~NO$,$"$j$^$9!#(B
$BIaDL$N%-!<$H%U%!%s%/%7%g%s%-!<$G$9!#(B
$BIaDL$N%-!<$OJ8;z$KBP1~$7$^$9!#(B
$B$=$l$i$,@8@.$9$k%$%Y%s%H$O!"(BLisp$B$G$OJ8;z$H$7$FI=8=$5$l$^$9!#(B
$BJ8;z%$%Y%s%H$N%$%Y%s%H7?$OJ8;z<+?H!J@0?t!K$G$9!#(B
@ref{Classifying Events}$B$r;2>H$7$F$/$@$5$$!#(B

@c @cindex modifier bits (of input character)
@c @cindex basic code (of input character)
@cindex $B=$>~%S%C%H!JF~NOJ8;z!K(B
@cindex $B4pK\%3!<%I!JF~NOJ8;z!K(B
@c An input character event consists of a @dfn{basic code} between 0 and
@c 524287, plus any or all of these @dfn{modifier bits}:
$BF~NOJ8;z%$%Y%s%H$O!"(B0$B$+$i(B524287$B$^$G$N(B@dfn{$B4pK\%3!<%I(B}$B!J(Bbasic code$B!K$H(B
$B0J2<$N(B@dfn{$B=$>~%S%C%H(B}$B!J(Bmodifier bit$B!K$NG$0U$NAH$_9g$o$;$G$9!#(B

@table @asis
@item meta
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{27}$
@end tex
@ifinfo
2**27
@end ifinfo
@c bit in the character code indicates a character
@c typed with the meta key held down.
$B$O!"%a%?%-!<$r2!$72<$2$J$,$iJ8;z$rBG$C$?$3$H$rI=$9!#(B

@item control
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{26}$
@end tex
@ifinfo
2**26
@end ifinfo
@c bit in the character code indicates a non-@sc{ASCII}
@c control character.
$B$OHs(B@sc{ASCII}$BJ8;z$N%3%s%H%m!<%kJ8;z$rI=$9!#(B

@c @sc{ASCII} control characters such as @kbd{C-a} have special basic
@c codes of their own, so Emacs needs no special bit to indicate them.
@c Thus, the code for @kbd{C-a} is just 1.
@kbd{C-a}$B$J$I$N(B@sc{ASCII}$B%3%s%H%m!<%kJ8;z$K$O(B
$BFH<+$NFCJL$J4pK\%3!<%I$,$"$k$?$a!"(B
Emacs$B$O$=$l$rI=$9$?$a$NFCJL$J%S%C%H$rI,MW$H$7$J$$!#(B
$B$D$^$j!"(B@kbd{C-a}$B$N%3!<%I$OC1$K(B1$B$G$"$k!#(B

@c But if you type a control combination not in @sc{ASCII}, such as
@c @kbd{%} with the control key, the numeric value you get is the code
@c for @kbd{%} plus
$B$7$+$7!"%3%s%H%m!<%k%-!<$r;H$C$?(B@kbd{%}$B$J$I$N(B
@sc{ASCII}$B$K$J$$%3%s%H%m!<%k$H$NAH$_9g$o$;$rBG$C$?>l9g!"(B
$BF@$i$l$k?tCM$O(B@kbd{%}$B$N%3!<%I$K(B
@tex
$2^{26}$
@end tex
@ifinfo
2**26
@end ifinfo
@c (assuming the terminal supports non-@sc{ASCII}
@c control characters).
$B$r2C$($?$b$N$G$"$k(B
$B!JC<Kv$GHs(B@sc{ASCII}$B$N%3%s%H%m!<%kJ8;z$r07$($k$H$7$F!K!#(B

@item shift
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{25}$
@end tex
@ifinfo
2**25
@end ifinfo
@c bit in the character code indicates an @sc{ASCII} control
@c character typed with the shift key held down.
$B$O!"%7%U%H%-!<$r2!$72<$2$J$,$i(B
@sc{ASCII}$B%3%s%H%m!<%kJ8;z$rBG$C$?$3$H$rI=$9!#(B

@c For letters, the basic code itself indicates upper versus lower case;
@c for digits and punctuation, the shift key selects an entirely different
@c character with a different basic code.  In order to keep within the
@c @sc{ASCII} character set whenever possible, Emacs avoids using the
$B1QJ8;z$G$O!"4pK\%3!<%I$=$N$b$N$,BgJ8;z$+>.J8;z$+$rI=$9!#(B
$B?t;zJ8;z$H6h@Z$jJ8;z$G$O!"(B
$B%7%U%H%-!<$O0[$J$k4pK\%3!<%I$N$^$C$?$/0[$J$kJ8;z$rA*$V!#(B
$B2DG=$J8B$j(B@sc{ASCII}$BJ8;z=89g$G$9$^$;$k$?$a$K!"(B
$B$3$l$i$NJ8;z$KBP$7$F$O!"(BEmacs$B$O%S%C%H(B
@tex
$2^{25}$
@end tex
@ifinfo
2**25
@end ifinfo
@c bit for those characters.
$B$r;H$o$J$$!#(B

@c However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
@c @kbd{C-a}, so Emacs uses the
$B$7$+$7!"(B@sc{ASCII}$B$G$O(B@kbd{C-A}$B$H(B@kbd{C-a}$B$r6hJL$G$-$J$$$?$a!"(B
Emacs$B$O!"(B@kbd{C-A}$B$G$O%S%C%H(B
@tex
$2^{25}$
@end tex
@ifinfo
2**25
@end ifinfo
@c bit in @kbd{C-A} and not in
@c @kbd{C-a}.
$B$r;H$&$,!"(B@kbd{C-a}$B$G$O$3$N%S%C%H$r;H$o$J$$!#(B

@item hyper
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{24}$
@end tex
@ifinfo
2**24
@end ifinfo
@c bit in the character code indicates a character
@c typed with the hyper key held down.
$B$O!"%O%$%Q!<%-!<$r2!$72<$2$J$,$iJ8;z$rBG$C$?$3$H$rI=$9!#(B

@item super
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{23}$
@end tex
@ifinfo
2**23
@end ifinfo
@c bit in the character code indicates a character
@c typed with the super key held down.
$B$O!"%9!<%Q!<%-!<$r2!$72<$2$J$,$iJ8;z$rBG$C$?$3$H$rI=$9!#(B

@item alt
@c The
$BJ8;z%3!<%I$N%S%C%H(B
@tex
$2^{22}$
@end tex
@ifinfo
2**22
@end ifinfo
@c bit in the character code indicates a character typed with
@c the alt key held down.  (On some terminals, the key labeled @key{ALT}
@c is actually the meta key.)
$B$O!"%"%k%H%-!<$r2!$72<$2$J$,$iJ8;z$rBG$C$?$3$H$rI=$9!#(B
$B!J(B@key{ALT}$B$H%i%Y%k$5$l$?%-!<$,<B:]$K$O%a%?%-!<$G$"$kC<Kv$bB8:_$9$k!#!K(B
@end table

@c   It is best to avoid mentioning specific bit numbers in your program.
@c To test the modifier bits of a character, use the function
@c @code{event-modifiers} (@pxref{Classifying Events}).  When making key
@c bindings, you can use the read syntax for characters with modifier bits
@c (@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
@c @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
@c specify the characters (@pxref{Changing Key Bindings}).  The function
@c @code{event-convert-list} converts such a list into an event type
@c (@pxref{Classifying Events}).
$BFI<T$N%W%m%0%i%`Fb$G$O!"(B
$BFCDj$N=$>~%S%C%H$NCM$rL@<($9$k$3$H$OHr$1$k$N$,:GNI$G$9!#(B
$BJ8;z$N=$>~%S%C%H$r8!::$9$k$K$O!"(B
$B4X?t(B@code{event-modifiers}$B!J(B@pxref{Classifying Events}$B!K$r;H$$$^$9!#(B
$B%-!<%P%$%s%G%#%s%0$r:n$k$H$-$K$O!"(B
$B!J(B@samp{\C-}$B!"(B@samp{\M-}$B$J$I$N!K=$>~%S%C%H$rH<$&J8;z$N(B
$BF~NOI=8=$r;H$$$^$9!#(B
@code{define-key}$B$G%-!<%P%$%s%G%#%s%0$r:n$k$H$-$K$O!"(B
$BJ8;z$N;XDj$K$O(B@code{(control hyper ?x)}$B$N$h$&$J%j%9%H$r;H$$$^$9(B
$B!J(B@pxref{Changing Key Bindings}$B!K!#(B
$B4X?t(B@code{event-convert-list}$B$O!"$=$N$h$&$J%j%9%H$r(B
$B%$%Y%s%H7?$KJQ49$7$^$9!J(B@pxref{Classifying Events}$B!K!#(B

@node Function Keys
@c @subsection Function Keys
@subsection $B%U%!%s%/%7%g%s%-!<(B

@c @cindex function keys
@cindex $B%U%!%s%/%7%g%s%-!<(B
@c Most keyboards also have @dfn{function keys}---keys that have names or
@c symbols that are not characters.  Function keys are represented in Emacs
@c Lisp as symbols; the symbol's name is the function key's label, in lower
@c case.  For example, pressing a key labeled @key{F1} places the symbol
@c @code{f1} in the input stream.
$B$[$H$s$I$N%-!<%\!<%I$K$O!"(B@dfn{$B%U%!%s%/%7%g%s%-!<(B}$B!J(Bfunction key$B!K!"(B
$B$D$^$j!"J8;z$G$O$J$$L>A0$d5-9f$N%-!<$,$"$j$^$9!#(B
Emacs Lisp$B$G$O!"%U%!%s%/%7%g%s%-!<$O%7%s%\%k$GI=8=$5$l$^$9!#(B
$B%7%s%\%k$N!J>.J8;z$N!KL>A0$,%U%!%s%/%7%g%s%-!<$N%i%Y%k$G$9!#(B
$B$?$H$($P!"(B@key{F1}$B$H$$$&%i%Y%k$N%-!<$r2!$9$H!"(B
$BF~NO%9%H%j!<%`$K$O%7%s%\%k(B@code{f1}$B$,CV$+$l$^$9!#(B

@c The event type of a function key event is the event symbol itself.
@c @xref{Classifying Events}.
$B%U%!%s%/%7%g%s%-!<%$%Y%s%H$N%$%Y%s%H7?$O!"%$%Y%s%H%7%s%\%k$=$l<+?H$G$9!#(B
@xref{Classifying Events}$B!#(B

@c Here are a few special cases in the symbol-naming convention for
@c function keys:
$B%U%!%s%/%7%g%s%-!<$KBP$9$k%7%s%\%kL?L>47=,$NFCNc$r0J2<$K<($7$^$9!#(B

@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
@c These keys correspond to common @sc{ASCII} control characters that have
@c special keys on most keyboards.
$B$3$l$i$N%-!<$O!"$[$H$s$I$N%-!<%\!<%I$K$"$kFCJL$J%-!<$r;}$D(B
$B0lHLE*$J(B@sc{ASCII}$B%3%s%H%m!<%kJ8;z$KBP1~$9$k!#(B

@c In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
@c terminal can distinguish between them, Emacs conveys the distinction to
@c Lisp programs by representing the former as the integer 9, and the
@c latter as the symbol @code{tab}.
@sc{ASCII}$B$G$O!"(B@kbd{C-i}$B$H(B@key{TAB}$B$OF1$8J8;z$G$"$k!#(B
$B$3$l$i$r6hJL$G$-$kC<Kv$G$O!"A0<T$r@0?t(B9$B!"8e<T$r%7%s%\%k(B@code{tab}$B$H(B
$BI=8=$9$k$3$H$G!"(BEmacs$B$O(BLisp$B%W%m%0%i%`$K6hJL$rEA$($k!#(B

@c Most of the time, it's not useful to distinguish the two.  So normally
@c @code{function-key-map} (@pxref{Translating Input}) is set up to map
@c @code{tab} into 9.  Thus, a key binding for character code 9 (the
@c character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
@c symbols in this group.  The function @code{read-char} likewise converts
@c these events into characters.
$B$[$H$s$I$N>lLL$G$O!"$3$l$i(B2$B$D$r6hJL$7$F$bM-MQ$G$O$J$$!#(B
$B$=$N$?$a!"DL>o!"(B@code{function-key-map}$B!J(B@pxref{Translating Input}$B!K$O!"(B
@code{tab}$B$r(B9$B$KBP1~IU$1$k$h$&$K$O@_Dj$7$F$"$k!#(B
$B$7$?$,$C$F!"J8;z%3!<%I(B9$B!JJ8;z(B@kbd{C-i}$B!K$KBP$9$k%-!<%P%$%s%G%#%s%0$O(B
@code{tab}$B$K$bE,MQ$5$l$k!#(B
$B$3$N<o$NB>$N%7%s%\%k$K$D$$$F$bF1MM$G$"$k!#(B
$B4X?t(B@code{read-char}$B$bF1MM$K$3$l$i$N%$%Y%s%H$rJ8;z$KJQ49$9$k!#(B

@c In @sc{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
@c converts into the character code 127 (@key{DEL}), not into code 8
@c (@key{BS}).  This is what most users prefer.
@sc{ASCII}$B$G$O!"(B@key{BS}$B$O<B:]$K$O(B@kbd{C-h}$B$G$"$k!#(B
$B$7$+$7!"(B@code{backspace}$B$OJ8;z%3!<%I(B127$B!J(B@key{DEL}$B!K$KJQ49$5$l!"(B
$BJ8;z%3!<%I(B8$B!J(B@key{BS}$B!K$K$OJQ49$5$l$J$$!#(B
$B$[$H$s$I$N%f!<%6!<$O$3$l$r9%$`!#(B

@item @code{left}, @code{up}, @code{right}, @code{down}
@c Cursor arrow keys
$B%+!<%=%kLp0u%-!<(B
@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
@c Keypad keys (to the right of the regular keyboard).
$B!JIaDL$N%-!<%\!<%I$N1&B&$K$"$k!K%-!<%Q%C%I$N%-!<!#(B
@item @code{kp-0}, @code{kp-1}, @dots{}
@c Keypad keys with digits.
$B%-!<%Q%C%I$N?t;z%-!<!#(B
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
@c Keypad PF keys.
$B%-!<%Q%C%I$N(BPF$B%-!<(B
@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
@c Keypad arrow keys.  Emacs normally translates these into the
@c corresponding non-keypad keys @code{home}, @code{left}, @dots{}
$B%-!<%Q%C%I$NLp0u%-!<!#(B
Emacs$B$O!"DL>o!"$3$l$i$rBP1~$9$k%-!<%Q%C%I$N$b$N$G$O$J$$(B
@code{home}$B!"(B@code{left}$B!"(B@dots{}$B$N%-!<$KJQ49$9$k!#(B
@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
@c Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
@c normally translates these into the like-named non-keypad keys.
$BIaDL$N%-!<$KBP1~$9$k%-!<%Q%C%I$N%-!<!#(B
Emacs$B$O!"DL>o!"F1$8L>A0$N%-!<%Q%C%I$N$b$N$G$O$J$$%-!<$KJQ49$9$k!#(B
@end table

@c You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
@c @key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
@c represent them is with prefixes in the symbol name:
$B%U%!%s%/%7%g%s%-!<$K$b(B@key{ALT}$B!"(B@key{CTRL}$B!"(B@key{HYPER}$B!"(B
@key{META}$B!"(B@key{SHIFT}$B!"(B@key{SUPER}$B$N=$>~%-!<$r;H$($^$9!#(B
$B$=$l$i$rI=8=$9$k$K$O!"%7%s%\%kL>$K@\F,<-$rIU$1$^$9!#(B

@table @samp
@item A-
@c The alt modifier.
$B%"%k%H=$>~!#(B
@item C-
@c The control modifier.
$B%3%s%H%m!<%k=$>~!#(B
@item H-
@c The hyper modifier.
$B%O%$%Q!<=$>~!#(B
@item M-
@c The meta modifier.
$B%a%?=$>~!#(B
@item S-
@c The shift modifier.
$B%7%U%H=$>~!#(B
@item s-
@c The super modifier.
$B%9!<%Q!<=$>~!#(B
@end table

@c Thus, the symbol for the key @key{F3} with @key{META} held down is
@c @code{M-f3}.  When you use more than one prefix, we recommend you
@c write them in alphabetical order; but the order does not matter in
@c arguments to the key-binding lookup and modification functions.
$B$7$?$,$C$F!"(B@key{META}$B$r2!$72<$2$?(B@key{F3}$B%-!<$N%7%s%\%k$O(B@code{M-f3}$B$G$9!#(B
$BJ#?t$N@\F,<-$r;H$&$H$-$K$O!"%"%k%U%!%Y%C%H=g$K=q$/$3$H$r4+$a$^$9$,!"(B
$B%-!<%P%$%s%G%#%s%0$NC5:w4X?t$d=$>~4X?t$N0z?t$G$O4X78$"$j$^$;$s!#(B

@node Mouse Events
@c @subsection Mouse Events
@subsection $B%^%&%9%$%Y%s%H(B

@c Emacs supports four kinds of mouse events: click events, drag events,
@c button-down events, and motion events.  All mouse events are represented
@c as lists.  The @sc{car} of the list is the event type; this says which
@c mouse button was involved, and which modifier keys were used with it.
@c The event type can also distinguish double or triple button presses
@c (@pxref{Repeat Events}).  The rest of the list elements give position
@c and time information.
Emacs$B$G$O(B4$B<oN`$N%^%&%9%$%Y%s%H!"$D$^$j!"%/%j%C%/%$%Y%s%H!"%I%i%C%0%$%Y%s%H!"(B
$B%\%?%s2!$72<$2%$%Y%s%H!"%b!<%7%g%s%$%Y%s%H$r07$($^$9!#(B
$B$9$Y$F$N%^%&%9%$%Y%s%H$O!"%j%9%H$GI=8=$7$^$9!#(B
$B%j%9%H$N(B@sc{car}$B$O%$%Y%s%H7?$G$"$j!"(B
$B$I$N=$>~%-!<$H$H$b$K$I$N%^%&%9%\%?%s$r;H$C$?$+$rI=$7$^$9!#(B
$B%$%Y%s%H7?$G$O!"%@%V%k!JO"B3(B2$B2s!K!?%H%j%W%k!JO"B3(B3$B2s!K$N(B
$B2!$72<$2$b6hJL$G$-$^$9!J(B@pxref{Repeat Events}$B!K!#(B
$B%j%9%H$N;D$j$NMWAG$O!"0LCV>pJs$H;~4V>pJs$G$9!#(B

@c For key lookup, only the event type matters: two events of the same type
@c necessarily run the same command.  The command can access the full
@c values of these events using the @samp{e} interactive code.
@c @xref{Interactive Codes}.
$B%-!<$NC5:w$G$O!"%$%Y%s%H7?$N$_$,0UL#$r;}$A$^$9!#(B
$B7?$,F1$8$G$"$l$P!"0[$J$k%$%Y%s%H$G$bF1$8%3%^%s%I$r<B9T$7$^$9!#(B
$B%3%^%s%I$G$O!"BPOC;XDj%3!<%I(B@samp{e}$B$rMQ$$$F%$%Y%s%H$N40A4$JCM$r;2>H$G$-$^$9!#(B
@xref{Interactive Codes}$B!#(B

@c A key sequence that starts with a mouse event is read using the keymaps
@c of the buffer in the window that the mouse was in, not the current
@c buffer.  This does not imply that clicking in a window selects that
@c window or its buffer---that is entirely under the control of the command
@c binding of the key sequence.
$B%^%&%9%$%Y%s%H$G;O$^$k%-!<Ns$O!"%+%l%s%H%P%C%U%!$N%-!<%^%C%W$G$O$J$/!"(B
$B%^%&%9$,F~$C$F$$$k%&%#%s%I%&$N%P%C%U%!$N%-!<%^%C%W$rMQ$$$FFI$^$l$^$9!#(B
$B$D$^$j!"$"$k%&%#%s%I%&Fb$G%/%j%C%/$7$F$b!"(B
$BEv3:%&%#%s%I%&$d%P%C%U%!$rA*Br$9$k$H$O8B$i$:!"(B
$B$=$NF0:n$O%-!<Ns$N%3%^%s%I%P%$%s%G%#%s%0$G40A4$K@)8f$5$l$^$9!#(B

@node Click Events
@c @subsection Click Events
@subsection $B%/%j%C%/%$%Y%s%H(B
@c @cindex click event
@c @cindex mouse click event
@cindex $B%/%j%C%/%$%Y%s%H(B
@cindex $B%^%&%9%/%j%C%/%$%Y%s%H(B

@c When the user presses a mouse button and releases it at the same
@c location, that generates a @dfn{click} event.  Mouse click events have
@c this form:
$B%f!<%6!<$,%^%&%9$N%\%?%s$rF1$8>l=j$G2!$72<$2$F$+$iN%$9$H!"(B
@dfn{$B%/%j%C%/(B}$B!J(Bclick$B!K%$%Y%s%H$,@8@.$5$l$^$9!#(B
$B%^%&%9%/%j%C%/%$%Y%s%H$O$D$.$N7A<0$G$9!#(B

@example
(@var{event-type}
 (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp})
 @var{click-count})
@end example

@c Here is what the elements normally mean:
$BDL>o$N3FMWAG$N0UL#$O$D$.$N$H$*$j$G$9!#(B

@table @asis
@item @var{event-type}
@c This is a symbol that indicates which mouse button was used.  It is
@c one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
@c buttons are numbered left to right.
$B$I$N%^%&%9%\%?%s$,;H$o$l$?$+$rI=$9%7%s%\%k!#(B
$B%\%?%s$r:8$+$i1&$XHV9f$rIU$1$F!"(B
$B%7%s%\%k(B@code{mouse-1}$B!"(B@code{mouse-2}$B!"(B@dots{}$B$N(B1$B$D$G$"$k!#(B

@c You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
@c @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
@c and super, just as you would with function keys.
$B%U%!%s%/%7%g%s%-!<$N>l9g$HF1MM$K!"(B
$B%"%k%H!"%3%s%H%m!<%k!"%O%$%Q!<!"%a%?!"%7%U%H!"%9!<%Q!<$N(B
$B=$>~%-!<$rI=$9@\F,<-(B@samp{A-}$B!"(B@samp{C-}$B!"(B@samp{H-}$B!"(B@samp{M-}$B!"(B
@samp{S-}$B!"(B@samp{s-}$B$b;H$($k!#(B

@c This symbol also serves as the event type of the event.  Key bindings
@c describe events by their types; thus, if there is a key binding for
@c @code{mouse-1}, that binding would apply to all events whose
@c @var{event-type} is @code{mouse-1}.
$B$3$N%7%s%\%k$O%$%Y%s%H$N%$%Y%s%H7?$H$7$F$NLr3d$b2L$?$9!#(B
$B%-!<%P%$%s%G%#%s%0$O%$%Y%s%H7?$G%$%Y%s%H$r;XDj$9$k!#(B
$B$7$?$,$C$F!"(B@code{mouse-1}$B$KBP$9$k%-!<%P%$%s%G%#%s%0$O!"(B
$B%$%Y%s%H7?(B@var{event-type}$B$,(B@code{mouse-1}$B$G$"$k$9$Y$F$N%$%Y%s%H$KE,MQ$5$l$k!#(B

@item @var{window}
@c This is the window in which the click occurred.
$B%/%j%C%/$r9T$C$?%&%#%s%I%&!#(B

@item @var{x}, @var{y}
@c These are the pixel-denominated coordinates of the click, relative to
@c the top left corner of @var{window}, which is @code{(0 . 0)}.
$B%&%#%s%I%&(B@var{window}$B$N:8>eC<$r(B@code{(0 . 0)}$B$H$7$?(B
$B%/%j%C%/0LCV$N%T%/%;%kC10L$N:BI8!#(B

@item @var{buffer-pos}
@c This is the buffer position of the character clicked on.
$B%/%j%C%/$7$?J8;z$N%P%C%U%!Fb0LCV!#(B

@item @var{timestamp}
@c This is the time at which the event occurred, in milliseconds.  (Since
@c this value wraps around the entire range of Emacs Lisp integers in about
@c five hours, it is useful only for relating the times of nearby events.)
$B%$%Y%s%H$,H/@8$7$?$H$-$N%_%jICC10L$N;~9o!#(B
$B!J$3$NCM$O!"(BEmacs Lisp$B$N@0?t$NHO0O$G$OLs(B5$B;~4V$G0l<~$9$k$N$G!"(B
$B;~4VE*$K6aK5$N%$%Y%s%H$r4XO"IU$1$k>l9g$K$N$_M-MQ$G$"$k!#!K(B

@item @var{click-count}
@c This is the number of rapid repeated presses so far of the same mouse
@c button.  @xref{Repeat Events}.
$BF1$8%^%&%9%\%?%s$rAGAa$/2!$72<$2$?7+$jJV$72s?t!#(B
@pxref{Repeat Events}$B!#(B
@end table

@c The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
@c different when the event location is in a special part of the screen,
@c such as the mode line or a scroll bar.
$B%b!<%I9T$d%9%/%m!<%k%P!<$J$I$N%9%/%j!<%s$NFCJL$JItJ,$GH/@8$7$?%$%Y%s%H$G$O!"(B
@var{buffer-pos}$B!"(B@var{x}$B$H(B@var{y}$B$N0UL#$O>/!90[$J$j$^$9!#(B

@c If the location is in a scroll bar, then @var{buffer-pos} is the symbol
@c @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
@c @code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
@c . @var{whole})}, where @var{portion} is the distance of the click from
@c the top or left end of the scroll bar, and @var{whole} is the length of
@c the entire scroll bar.
$B%9%/%m!<%k%P!<$NFbB&$G$N%/%j%C%/$G$O!"(B
@var{buffer-pos}$B$O%7%s%\%k(B@code{vertical-scroll-bar}$B$+(B
@code{horizontal-scroll-bar}$B$G$"$j!"(B
@code{(@var{x} . @var{y})}$B$O(B@code{(@var{portion} . @var{whole})}$B$K(B
$BCV$-49$($i$l$^$9!#(B
$B$3$3$G!"(B@var{portion}$B$O%9%/%m!<%k%P!<$N@hF,$d:8C<$+$i$N%/%j%C%/0LCV!"(B
@var{whole}$B$O%9%/%m!<%k%P!<A4BN$ND9$5$G$9!#(B

@c If the position is on a mode line or the vertical line separating
@c @var{window} from its neighbor to the right, then @var{buffer-pos} is
@c the symbol @code{mode-line} or @code{vertical-line}.  For the mode line,
@c @var{y} does not have meaningful data.  For the vertical line, @var{x}
@c does not have meaningful data.
$B%b!<%I9T$d%&%#%s%I%&(B@var{window}$B$r1&NY$N$b$N$H6h@Z$k(B
$B=DJ}8~$N6h@Z$j9T$NFbB&$G$O!"(B
@var{buffer-pos}$B$O%7%s%\%k(B@code{mode-line}$B$+(B@code{vertical-line}$B$G$9!#(B
$B%b!<%I9T$G$O!"(B@var{y}$B$O0UL#$N$"$k%G!<%?$G$O$"$j$^$;$s!#(B
$B=DJ}8~$N6h@Z$j9T$G$O!"(B@var{x}$B$O0UL#$N$"$k%G!<%?$G$O$"$j$^$;$s!#(B

@c In one special case, @var{buffer-pos} is a list containing a symbol (one
@c of the symbols listed above) instead of just the symbol.  This happens
@c after the imaginary prefix keys for the event are inserted into the
@c input stream.  @xref{Key Sequence Input}.
1$B$D$NFCJL$J>lLL$G$O!"(B
@var{buffer-pos}$B$OC10l$N%7%s%\%k$G$O$J$/!J>e$K=R$Y$?(B1$B$D$N!K%7%s%\%k$r(B
$B4^$s$@%j%9%H$K$J$j$^$9!#(B
$B%$%Y%s%H$KBP$9$k2>A[E*$J%W%l%U%#%C%/%9%-!<$rF~NO%9%H%j!<%`$KA^F~$9$k$H(B
$B$3$N$h$&$K$J$j$^$9!#(B
@xref{Key Sequence Input}$B!#(B

@node Drag Events
@c @subsection Drag Events
@subsection $B%I%i%C%0%$%Y%s%H(B
@c @cindex drag event
@c @cindex mouse drag event
@cindex $B%I%i%C%0%$%Y%s%H(B
@cindex $B%^%&%9%I%i%C%0%$%Y%s%H(B

@c With Emacs, you can have a drag event without even changing your
@c clothes.  A @dfn{drag event} happens every time the user presses a mouse
@c button and then moves the mouse to a different character position before
@c releasing the button.  Like all mouse events, drag events are
@c represented in Lisp as lists.  The lists record both the starting mouse
@c position and the final position, like this:
Emacs$B$K$O!"%I%i%C%0%$%Y%s%H$,$"$j$^$9!#(B
$B%f!<%6!<$,%^%&%9%\%?%s$r2!$72<$2$F$+$i!"(B
$B%\%?%s$rN%$9$^$($KJL$NJ8;z0LCV$X%^%&%9$rF0$+$9$H(B
@dfn{$B%I%i%C%0(B}$B!J(Bdrag$B!K%$%Y%s%H$,H/@8$7$^$9!#(B
$B%^%&%9$N$9$Y$F$N%$%Y%s%H$N$h$&$K!"(BLisp$B$G$O%I%i%C%0%$%Y%s%H$O(B
$B%j%9%H$H$7$FI=8=$5$l$^$9!#(B
$B$D$.$N$h$&$K!"%j%9%H$O3+;O%^%&%90LCV$H=*N;0LCV$r5-O?$7$F$$$^$9!#(B

@example
(@var{event-type}
 (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
 (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
 @var{click-count})
@end example

@c For a drag event, the name of the symbol @var{event-type} contains the
@c prefix @samp{drag-}.  For example, dragging the mouse with button 2 held
@c down generates a @code{drag-mouse-2} event.  The second and third
@c elements of the event give the starting and ending position of the drag.
@c Aside from that, the data have the same meanings as in a click event
@c (@pxref{Click Events}).  You can access the second element of any mouse
@c event in the same way, with no need to distinguish drag events from
@c others.
$B%I%i%C%0%$%Y%s%H$G$O!"%7%s%\%k(B@var{event-type}$B$NL>A0$K$O(B
$B@\F,<-(B@samp{drag-}$B$,IU$-$^$9!#(B
$B$?$H$($P!"%\%?%s(B2$B$r2!$72<$2$F%^%&%9$r%I%i%C%0$9$k$H(B
$B%$%Y%s%H(B@code{drag-mouse-2}$B$,@8@.$5$l$^$9!#(B
$B%$%Y%s%H$N(B2$BHVL\$H(B3$BHVL\$NMWAG$O!"%I%i%C%0$N3+;O0LCV$H=*N;0LCV$rM?$($^$9!#(B
$B$J$*!"%G!<%?$K$O%/%j%C%/%$%Y%s%H$HF1$80UL#$,$"$j$^$9!J(B@pxref{Click Events}$B!K!#(B
$B%I%i%C%0%$%Y%s%H$+$I$&$+$r6hJL$;$:$K!"(B
$B%^%&%9$NG$0U$N%$%Y%s%H$N(B2$BHVL\$NMWAG$OF1$8J}K!$G;2>H$G$-$^$9!#(B

@c The @samp{drag-} prefix follows the modifier key prefixes such as
@c @samp{C-} and @samp{M-}.
$B@\F,<-(B@samp{drag-}$B$O!"(B
@samp{C-}$B$d(B@samp{M-}$B$N$h$&$J=$>~%-!<@\F,<-$KB3$-$^$9!#(B

@c If @code{read-key-sequence} receives a drag event that has no key
@c binding, and the corresponding click event does have a binding, it
@c changes the drag event into a click event at the drag's starting
@c position.  This means that you don't have to distinguish between click
@c and drag events unless you want to.
@code{read-key-sequence}$B$,!"(B
$B%-!<%P%$%s%G%#%s%0$r;}$?$J$$%I%i%C%0%$%Y%s%H$r<u$1<h$j!"$+$D!"(B
$B$=$l$KBP1~$9$k%/%j%C%/%$%Y%s%H$K$O%P%$%s%G%#%s%0$,$"$k>l9g!"(B
$B%I%i%C%0%$%Y%s%H$N3+;O0LCV$r%/%j%C%/0LCV$H$9$k%/%j%C%/%$%Y%s%H$KJQ49$7$^$9!#(B
$B$D$^$j!"K>$^$J$1$l$P!"FI<T$O%/%j%C%/%$%Y%s%H$H%I%i%C%0%$%Y%s%H$r6hJL$9$k(B
$BI,MW$,$"$j$^$;$s!#(B

@node Button-Down Events
@c @subsection Button-Down Events
@subsection $B%\%?%s2!$72<$2%$%Y%s%H(B
@c @cindex button-down event
@cindex $B%\%?%s2!$72<$2%$%Y%s%H(B

@c Click and drag events happen when the user releases a mouse button.
@c They cannot happen earlier, because there is no way to distinguish a
@c click from a drag until the button is released.
$B%/%j%C%/%$%Y%s%H$H%I%i%C%0%$%Y%s%H$O!"(B
$B%f!<%6!<$,%^%&%9%\%?%s$rN%$7$?$H$-$KH/@8$7$^$9!#(B
$B%\%?%s$rN%$9$^$G$O%/%j%C%/$H%I%i%C%0$r6hJL$9$kJ}K!$,$J$$$?$a!"(B
$B%\%?%s$rN%$9$^$GH/@8$7$($^$;$s!#(B

@c If you want to take action as soon as a button is pressed, you need to
@c handle @dfn{button-down} events.@footnote{Button-down is the
@c conservative antithesis of drag.}  These occur as soon as a button is
@c pressed.  They are represented by lists that look exactly like click
@c events (@pxref{Click Events}), except that the @var{event-type} symbol
@c name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
@c modifier key prefixes such as @samp{C-} and @samp{M-}.
$B%\%?%s$r2!$72<$2$?$i$?$@$A$KF0:n$r;O$a$?$$>l9g$K$O!"(B
$BFI<T$O(B@dfn{$B%\%?%s2!$72<$2(B}$B!J(Bbutton-down$B!K%$%Y%s%H$r=hM}$9$kI,MW$,$"$j$^$9!#(B
@footnote{$B!V%\%?%s2!$72<$2!W$O!"!V%I%i%C%0!W$NBP6g!#(B}
$B%\%?%s$r2!$72<$2$k$H$?$@$A$KH/@8$7$^$9!#(B
$B$=$l$i$O!"%7%s%\%k(B@var{event-type}$B$NL>A0$K(B
$B@\F,<-(B@samp{down-}$B$,$"$k$3$H$r=|$1$P!"(B
$B%/%j%C%/%$%Y%s%H!J(B@pxref{Click Events}$B!K$H$^$C$?$/F1$8%j%9%H$GI=8=$5$l$^$9!#(B
$B@\F,<-(B@samp{down-}$B$O!"(B@samp{C-}$B$d(B@samp{M-}$B$N$h$&$J=$>~%-!<@\F,<-$KB3$-$^$9!#(B

@c The function @code{read-key-sequence} ignores any button-down events
@c that don't have command bindings; therefore, the Emacs command loop
@c ignores them too.  This means that you need not worry about defining
@c button-down events unless you want them to do something.  The usual
@c reason to define a button-down event is so that you can track mouse
@c motion (by reading motion events) until the button is released.
@c @xref{Motion Events}.
$B4X?t(B@code{read-key-sequence}$B$O!"(B
$B%3%^%s%I%P%$%s%G%#%s%0$r;}$?$J$$%\%?%s2!$72<$2%$%Y%s%H$rL5;k$7$^$9!#(B
$B$7$?$,$C$F!"(BEmacs$B$N%3%^%s%I%k!<%W$b$=$l$i$rL5;k$7$^$9!#(B
$B$D$^$j!"FI<T$,%\%?%s2!$72<$2%$%Y%s%H$G$J$K$+$r$7$?$$$N$G$J$1$l$P!"(B
$BFI<T$O%\%?%s2!$72<$2%$%Y%s%H$rDj5A$9$kI,MW$O$"$j$^$;$s!#(B
$B%\%?%s2!$72<$2%$%Y%s%H$rDj5A$9$kM}M3$O!"(B
$B%\%?%s$,N%$5$l$k$^$G!J%b!<%7%g%s%$%Y%s%H$rFI$s$G!K%^%&%9$NF0$-$r(B
$BDI@W$9$k$?$a$G$9!#(B
@xref{Motion Events}$B!#(B

@node Repeat Events
@c @subsection Repeat Events
@subsection $B7+$jJV$7%$%Y%s%H(B
@c @cindex repeat events
@c @cindex double-click events
@c @cindex triple-click events
@cindex $B7+$jJV$7%$%Y%s%H(B
@cindex $B%@%V%k%/%j%C%/%$%Y%s%H(B
@cindex $B%H%j%W%k%/%j%C%/%$%Y%s%H(B

@c If you press the same mouse button more than once in quick succession
@c without moving the mouse, Emacs generates special @dfn{repeat} mouse
@c events for the second and subsequent presses.
$B%^%&%9$rF0$+$5$:$KF10l$N%^%&%9%\%?%s$rAGAa$/O"B3$7$F2!$72<$2$k$H!"(B
Emacs$B$O(B2$B2sL\0J9_$N2!$72<$2$KBP$7$F(B
$BFCJL$J(B@dfn{$B7+$jJV$7(B}$B!J(Brepeat$B!K%^%&%9%$%Y%s%H$r@8@.$7$^$9!#(B

@c The most common repeat events are @dfn{double-click} events.  Emacs
@c generates a double-click event when you click a button twice; the event
@c happens when you release the button (as is normal for all click
@c events).
$B$b$C$H$b0lHLE*$J7+$jJV$7%$%Y%s%H$O(B@dfn{$B%@%V%k%/%j%C%/(B}$B!J(Bdouble-click$B!K(B
$B%$%Y%s%H$G$9!#(B
$B%\%?%s$r(B2$B2s%/%j%C%/$9$k$H!"(BEmcas$B$O%@%V%k%/%j%C%/%$%Y%s%H$r@8@.$7$^$9!#(B
$B!JB>$N$9$Y$F$N%/%j%C%/%$%Y%s%H$N$h$&$K!KFI<T$,%\%?%s$rN%$7$?$H$-$K(B
$B%$%Y%s%H$,@8@.$5$l$^$9!#(B

@c The event type of a double-click event contains the prefix
@c @samp{double-}.  Thus, a double click on the second mouse button with
@c @key{meta} held down comes to the Lisp program as
@c @code{M-double-mouse-2}.  If a double-click event has no binding, the
@c binding of the corresponding ordinary click event is used to execute
@c it.  Thus, you need not pay attention to the double click feature 
@c unless you really want to.
$B%@%V%k%/%j%C%/%$%Y%s%H$N%$%Y%s%H7?$K$O!"@\F,<-(B@samp{double-}$B$,4^$^$l$^$9!#(B
$B$7$?$,$C$F!"(B@key{meta}$B$r2!$72<$2$F(B2$BHVL\$N%\%?%s$r%@%V%k%/%j%C%/$9$k$H!"(B
Lisp$B%W%m%0%i%`$K$O(B@code{M-double-mouse-2}$B$,Aw$i$l$^$9!#(B
$B%@%V%k%/%j%C%/%$%Y%s%H$K%P%$%s%G%#%s%0$,$J$1$l$P!"(B
$BBP1~$9$kIaDL$N%/%j%C%/%$%Y%s%H$rMQ$$$F<B9T$7$^$9!#(B
$B$7$?$,$C$F!"<B:]$KMxMQ$7$?$/$J$$8B$j$O!"(B
$BFI<T$O%@%V%k%/%j%C%/5!G=$KCm0U$9$kI,MW$O$"$j$^$;$s!#(B

@c When the user performs a double click, Emacs generates first an ordinary
@c click event, and then a double-click event.  Therefore, you must design
@c the command binding of the double click event to assume that the
@c single-click command has already run.  It must produce the desired
@c results of a double click, starting from the results of a single click.
$B%f!<%6!<$,%@%V%k%/%j%C%/$9$k$H!"(BEmacs$B$O$^$:IaDL$N%/%j%C%/%$%Y%s%H$r@8@.$7!"(B
$B$D$.$K%@%V%k%/%j%C%/%$%Y%s%H$r@8@.$7$^$9!#(B
$B$7$?$,$C$F!"%@%V%k%/%j%C%/%$%Y%s%H$N%3%^%s%I%P%$%s%G%#%s%0$G$O!"(B
$B$9$G$KIaDL$N%/%j%C%/%3%^%s%I$,F0:n:Q$_$G$"$k$H2>Dj$7$F@_7W$9$kI,MW$,$"$j$^$9!#(B
$BIaDL$N%/%j%C%/$N7k2L$r$b$H$KK>$_$N%@%V%k%/%j%C%/$N7k2L$rF@$k$h$&$K$7$^$9!#(B

@c This is convenient, if the meaning of a double click somehow ``builds
@c on'' the meaning of a single click---which is recommended user interface
@c design practice for double clicks.
$BIaDL$N%/%j%C%/$N0UL#$K%@%V%k%/%j%C%/$N0UL#$r(B
$B!XDI2C!Y$9$k$h$&$K$9$k$HJXMx$G$9!#(B
$B%@%V%k%/%j%C%/$N%f!<%6!<%$%s%?!<%U%'%$%9$O$3$N$h$&$K$9$k$3$H$r4+$a$^$9!#(B

@c If you click a button, then press it down again and start moving the
@c mouse with the button held down, then you get a @dfn{double-drag} event
@c when you ultimately release the button.  Its event type contains
@c @samp{double-drag} instead of just @samp{drag}.  If a double-drag event
@c has no binding, Emacs looks for an alternate binding as if the event
@c were an ordinary drag.
$B%\%?%s$r%/%j%C%/$7$F!"$U$?$?$S%\%?%s$r2!$72<$2$F$=$N$^$^%^%&%9$rF0$+$9$H!"(B
$B:G=*E*$K%\%?%s$rN%$7$?;~E@$G!"(B@dfn{$B%@%V%k%I%i%C%0(B}$B!J(Bdouble-drag$B!K%$%Y%s%H$,(B
$B@8@.$5$l$^$9!#(B
$B$=$N%$%Y%s%H7?$K$O(B@samp{drag}$B$N$+$o$j$K(B@samp{double-drag}$B$,4^$^$l$^$9!#(B
$B%@%V%k%I%i%C%0%$%Y%s%H$K%P%$%s%G%#%s%0$,$J$1$l$P!"(B
Emacs$B$OIaDL$N%I%i%C%0%$%Y%s%H$H$7$F%P%$%s%G%#%s%0$rC5$7$^$9!#(B

@c Before the double-click or double-drag event, Emacs generates a
@c @dfn{double-down} event when the user presses the button down for the
@c second time.  Its event type contains @samp{double-down} instead of just
@c @samp{down}.  If a double-down event has no binding, Emacs looks for an
@c alternate binding as if the event were an ordinary button-down event.
@c If it finds no binding that way either, the double-down event is
@c ignored.
$B%@%V%k%/%j%C%/%$%Y%s%H$d%@%V%k%I%i%C%0%$%Y%s%H$r@8@.$9$k$^$($K!"(B
$B%f!<%6!<$,%\%?%s$r(B2$B2sL\$K2!$72<$2$?$H$-!"(B
Emacs$B$O(B@dfn{$B%@%V%k%@%&%s(B}$B!J(Bdouble-down$B!K%$%Y%s%H$r@8@.$7$^$9!#(B
$B$3$N%$%Y%s%H7?$K$O(B@samp{down}$B$N$+$o$j$K(B@samp{double-down}$B$,4^$^$l$^$9!#(B
$B%@%V%k%@%&%s%$%Y%s%H$K%P%$%s%G%#%s%0$,$J$1$l$P!"(B
Emacs$B$OIaDL$N%\%?%s2!$72<$2%$%Y%s%H$H$7$F%P%$%s%G%#%s%0$rC5$7$^$9!#(B
$B$I$A$i$G$b%P%$%s%G%#%s%0$,$_$D$+$i$J$1$l$P!"%@%V%k%@%&%s%$%Y%s%H$OL5;k$7$^$9!#(B

@c To summarize, when you click a button and then press it again right
@c away, Emacs generates a down event and a click event for the first
@c click, a double-down event when you press the button again, and finally
@c either a double-click or a double-drag event.
$B$^$H$a$k$H!"%\%?%s$r%/%j%C%/$7$F$?$@$A$K:FEY%\%?%s$r2!$72<$2$k$H!"(B
Emacs$B$O!"$O$8$a$N%/%j%C%/$KBP$7$F%\%?%s2!$72<$2%$%Y%s%H$H(B
$B%/%j%C%/%$%Y%s%H$r@8@.$7!"(B
$B:FEY%\%?%s$r2!$72<$2$k$H%@%V%k%@%&%s%$%Y%s%H$r@8@.$7!"(B
$B:G8e$K%@%V%k%/%j%C%/%$%Y%s%H$+%@%V%k%I%i%C%0%$%Y%s%H$r@8@.$7$^$9!#(B

@c If you click a button twice and then press it again, all in quick
@c succession, Emacs generates a @dfn{triple-down} event, followed by
@c either a @dfn{triple-click} or a @dfn{triple-drag}.  The event types of
@c these events contain @samp{triple} instead of @samp{double}.  If any
@c triple event has no binding, Emacs uses the binding that it would use
@c for the corresponding double event.
$B%\%?%s$r(B2$B2s%/%j%C%/$7$F$+$i:FEY2!$72<$2$kA`:n$rAGAa$/9T$&$H!"(B
Emacs$B$O!"(B@dfn{$B%H%j%W%k%@%&%s(B}$B!J(Btriple-down$B!K%$%Y%s%H$KB3$1$F(B
@dfn{$B%H%j%W%k%/%j%C%/(B}$B!J(Btriple-click$B!K%$%Y%s%H$+(B
@dfn{$B%H%j%W%k%I%i%C%0(B}$B!J(Btriple-drag$B!K%$%Y%s%H$r@8@.$7$^$9!#(B
$B$3$l$i$N%$%Y%s%H7?$K$O(B@samp{double}$B$N$+$o$j$K(B@samp{triple}$B$,4^$^$l$^$9!#(B
$B%H%j%W%k$N%$%Y%s%H$K%P%$%s%G%#%s%0$,$J$1$l$P!"(B
Emacs$B$OBP1~$9$k%@%V%k$N%$%Y%s%H$r;H$$$^$9!#(B

@c If you click a button three or more times and then press it again, the
@c events for the presses beyond the third are all triple events.  Emacs
@c does not have separate event types for quadruple, quintuple, etc.@:
@c events.  However, you can look at the event list to find out precisely
@c how many times the button was pressed.
$B%\%?%s$r(B3$B2s0J>e%/%j%C%/$7$F$+$i:FEY2!$72<$2$k$H!"(B
3$B2sL\0J9_$N2!$72<$2$KBP$9$k%$%Y%s%H$O$9$Y$F%H%j%W%k$N%$%Y%s%H$G$9!#(B
Emacs$B$O!"%/%"%I%i%W%k!J(B4$B2s!K!"%/%$%s%?%W%k!J(B5$B2s!K!"!D$J$I$N(B
$B%$%Y%s%H$O@8@.$7$^$;$s!#(B
$B$7$+$7!"%$%Y%s%H%j%9%H$rD4$Y$l$P!"%\%?%s$r2?2s2!$7$?$+@53N$K$o$+$j$^$9!#(B

@defun event-click-count event
@c This function returns the number of consecutive button presses that led
@c up to @var{event}.  If @var{event} is a double-down, double-click or
@c double-drag event, the value is 2.  If @var{event} is a triple event,
@c the value is 3 or greater.  If @var{event} is an ordinary mouse event
@c (not a repeat event), the value is 1.
$B$3$N4X?t$O!"%$%Y%s%H(B@var{event}$B$K$*$$$F%\%?%s$,O"B3$7$F2!$5$l$?2s?t$rJV$9!#(B
@var{event}$B$,!"%@%V%k%@%&%s%$%Y%s%H!"%@%V%k%/%j%C%/%$%Y%s%H!"(B
$B%@%V%k%I%i%C%0%$%Y%s%H$G$"$k$H!"CM$O(B2$B$G$"$k!#(B
@var{event}$B$,%H%j%W%k$N%$%Y%s%H$G$"$k$H!"CM$O(B3$B$+$=$l0J>e$G$"$k!#(B
@var{event}$B$,!J7+$jJV$7%$%Y%s%H$G$O$J$$!KIaDL$N%^%&%9%$%Y%s%H$G$"$k$H!"(B
$BCM$O(B1$B$G$"$k!#(B
@end defun

@defvar double-click-time
@c To generate repeat events, successive mouse button presses must be at
@c the same screen position, and the number of milliseconds between
@c successive button presses must be less than the value of
@c @code{double-click-time}.  Setting @code{double-click-time} to
@c @code{nil} disables multi-click detection entirely.  Setting it to
@c @code{t} removes the time limit; Emacs then detects multi-clicks by
@c position only.
$B7+$jJV$7%$%Y%s%H$,@8@.$5$l$k$?$a$K$O!"(B
$BF1$8%9%/%j!<%s0LCV$K$*$$$FO"B3$7$F%^%&%9%\%?%s$r2!$72<$2!"$7$+$b!"(B
$B3F2!$72<$2$N4V3V$O(B@code{double-click-time}$B$NCML$K~!J%_%jIC!K$G$"$kI,MW$,$"$k!#(B
@code{double-click-time}$B$K(B@code{nil}$B$r@_Dj$9$k$H!"(B
$BO"B3$7$?%/%j%C%/$N8!=P$r6X;_$9$k!#(B
@code{t}$B$r@_Dj$9$k$H;~4V@)8B$r$J$/$7!"(B
Emacs$B$OO"B3$7$?%/%j%C%/$N8!=P$r0LCV$@$1$G9T$&!#(B
@end defvar

@node Motion Events
@c @subsection Motion Events
@subsection $B%b!<%7%g%s%$%Y%s%H(B
@c @cindex motion event
@c @cindex mouse motion events
@cindex $B%b!<%7%g%s%$%Y%s%H(B
@cindex $B%^%&%9%b!<%7%g%s%$%Y%s%H(B

@c Emacs sometimes generates @dfn{mouse motion} events to describe motion
@c of the mouse without any button activity.  Mouse motion events are
@c represented by lists that look like this:
Emacs$B$O!"%\%?%sA`:n$rH<$o$J$$%^%&%9$N0\F0$rI=$9(B
@dfn{$B%^%&%9%b!<%7%g%s(B}$B!J(Bmouse motion$B!K%$%Y%s%H$r@8@.$9$k$3$H$,$"$j$^$9!#(B
$B%^%&%9%b!<%7%g%s%$%Y%s%H$O$D$.$N$h$&$J%j%9%H$GI=8=$5$l$^$9!#(B

@example
(mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
@end example

@c The second element of the list describes the current position of the
@c mouse, just as in a click event (@pxref{Click Events}).
$B%j%9%H$N(B2$BHVL\$NMWAG$O!"%/%j%C%/%$%Y%s%H!J(B@pxref{Click Events}$B!K$HF1MM$K!"(B
$B%^%&%9$N8=:_0LCV$rI=$7$^$9!#(B

@c The special form @code{track-mouse} enables generation of motion events
@c within its body.  Outside of @code{track-mouse} forms, Emacs does not
@c generate events for mere motion of the mouse, and these events do not
@c appear.  @xref{Mouse Tracking}.
$B%9%Z%7%c%k%U%)!<%`(B@code{track-mouse}$B$K$h$j!"(B
$B$=$NK\BN$NFbB&$G$O%b!<%7%g%s%$%Y%s%H$N@8@.$r2DG=$K$G$-$^$9!#(B
$B%U%)!<%`(B@code{track-mouse}$B$N30B&$G$O!"(B
Emacs$B$O%^%&%9$N0\F0$N$_$KBP$9$k%$%Y%s%H$r@8@.$7$J$$$N$G!"(B
$B$=$l$i$N%$%Y%s%H$O8=$l$^$;$s!#(B
@xref{Mouse Tracking}$B!#(B

@node Focus Events
@c @subsection Focus Events
@subsection $B%U%)!<%+%9%$%Y%s%H(B
@c @cindex focus event
@cindex $B%U%)!<%+%9%$%Y%s%H(B

@c Window systems provide general ways for the user to control which window
@c gets keyboard input.  This choice of window is called the @dfn{focus}.
@c When the user does something to switch between Emacs frames, that
@c generates a @dfn{focus event}.  The normal definition of a focus event,
@c in the global keymap, is to select a new frame within Emacs, as the user
@c would expect.  @xref{Input Focus}.
$B%&%#%s%I%&%7%9%F%`$O!"$I$N%&%#%s%I%&$K%-!<%\!<%IF~NO$rM?$($k$+$r(B
$B%f!<%6!<$,@)8f$9$k$?$a$N0lHLE*$JJ}K!$rDs6!$7$^$9!#(B
$B%&%#%s%I%&$rA*$V$3$H$r(B@dfn{$B%U%)!<%+%9(B}$B!J(Bfocus$B!K$H8F$S$^$9!#(B
$B%f!<%6!<$,(BEmacs$B$N%U%l!<%`$r@Z$jBX$($kA`:n$r9T$&$H!"(B
@dfn{$B%U%)!<%+%9%$%Y%s%H(B}$B!J(Bfocus event$B!K$,@8@.$5$l$^$9!#(B
$B%0%m!<%P%k%-!<%^%C%W$K$"$k%U%)!<%+%9%$%Y%s%H$NIaDL$NDj5A$O!"(B
Emcas$B$N?7$?$J%U%l!<%`$rA*Br$9$k$h$&$K$J$C$F$$$F!"(B
$B$3$l$O%f!<%6!<$,4|BT$9$k$3$H$G$9!#(B
@xref{Input Focus}$B!#(B

@c Focus events are represented in Lisp as lists that look like this:
Lisp$B$G$O!"%U%)!<%+%9%$%Y%s%H$O$D$.$N$h$&$J%j%9%H$GI=8=$5$l$^$9!#(B

@example
(switch-frame @var{new-frame})
@end example

@noindent
@c where @var{new-frame} is the frame switched to.
$B$3$3$G!"(B@var{new-frame}$B$O@Z$jBX$(@h$N%U%l!<%`$G$9!#(B

@c Most X window managers are set up so that just moving the mouse into a
@c window is enough to set the focus there.  Emacs appears to do this,
@c because it changes the cursor to solid in the new frame.  However, there
@c is no need for the Lisp program to know about the focus change until
@c some other kind of input arrives.  So Emacs generates a focus event only
@c when the user actually types a keyboard key or presses a mouse button in
@c the new frame; just moving the mouse between frames does not generate a
@c focus event.
X$B$N$[$H$s$I$N%&%#%s%I%&%^%M!<%8%c$O!"(B
$B%^%&%9$r%&%#%s%I%&$XF~$l$k$@$1$GEv3:%&%#%s%I%&$K%U%)!<%+%9$,@_Dj$5$l$k(B
$B$h$&$K$J$C$F$$$^$9!#(B
$B%U%l!<%`$K%^%&%9$,F~$k$H%+!<%=%k$N7A>u$rJQ99$9$k$N$G!"(B
Emacs$B$G$b$=$N$h$&$K$7$^$9!#(B
$B$7$+$7!"(BLisp$B%W%m%0%i%`$K$H$C$F$O!"(B
$B$J$s$i$+$NF~NO$,E~Ce$9$k$^$G$O%U%)!<%+%9$NJQ99$K$D$$$FCN$kI,MW$,$"$j$^$;$s!#(B
$B$=$N$?$a!"%f!<%6!<$,<B:]$K%-!<%\!<%I$N%-!<$rBG$D$+(B
$B?7$?$J%U%l!<%`$G%^%&%9%\%?%s$r2!$72<$2$?$H$-$@$1!"(B
Emacs$B$O%U%)!<%+%9%$%Y%s%H$r@8@.$7$^$9!#(B
$B%U%l!<%`4V$G%^%&%9$rF0$+$7$?$@$1$G$O!"%U%)!<%+%9%$%Y%s%H$O@8@.$5$l$^$;$s!#(B

@c A focus event in the middle of a key sequence would garble the
@c sequence.  So Emacs never generates a focus event in the middle of a key
@c sequence.  If the user changes focus in the middle of a key
@c sequence---that is, after a prefix key---then Emacs reorders the events
@c so that the focus event comes either before or after the multi-event key
@c sequence, and not within it.
$B%-!<Ns$NESCf$K%U%)!<%+%9%$%Y%s%H$,8=$l$k$H!"%-!<Ns$rMp$7$^$9!#(B
$B$=$N$?$a!"(BEmacs$B$O%-!<Ns$NESCf$K$O%U%)!<%+%9%$%Y%s%H$r@8@.$7$^$;$s!#(B
$B%f!<%6!<$,%-!<Ns$NESCf$G!"$D$^$j!"(B
$B%W%l%U%#%C%/%9%-!<$N$"$H$G%U%)!<%+%9$rJQ99$9$k$H!"(B
$BJ#?t%$%Y%s%H$N%-!<Ns$N$^$($+$&$7$m$K%U%)!<%+%9%$%Y%s%H$r0\F0$7!"(B
$BESCf$K$O8=$l$J$$$h$&$K(BEmacs$B$O%$%Y%s%H$N=g=x$rJB$SBX$($^$9!#(B

@node Misc Events
@c @subsection Miscellaneous Window System Events
@subsection $B%&%#%s%I%&%7%9%F%`$N$=$NB>$N%$%Y%s%H(B

@c A few other event types represent occurrences within the window system.
$B%&%#%s%I%&%7%9%F%`Fb$G5/$-$?$3$H$rI=$9B>$N%$%Y%s%H$b$"$j$^$9!#(B

@table @code
@c @cindex @code{delete-frame} event
@cindex $B%$%Y%s%H(B@code{delete-frame}
@cindex @code{delete-frame}$B%$%Y%s%H(B
@item (delete-frame (@var{frame}))
@c This kind of event indicates that the user gave the window manager
@c a command to delete a particular window, which happens to be an Emacs frame.
$B$3$N<o$N%$%Y%s%H$O!"(B
Emacs$B$N%U%l!<%`$G$"$k%&%#%s%I%&$r:o=|$9$k%3%^%s%I$r(B
$B%f!<%6!<$,%&%#%s%I%&%^%M!<%8%c$KM?$($?$3$H$rI=$9!#(B

@c The standard definition of the @code{delete-frame} event is to delete @var{frame}.
$B%$%Y%s%H(B@code{delete-frame}$B$NI8=`Dj5A$O%U%l!<%`(B@var{frame}$B$N:o=|$G$"$k!#(B

@c @cindex @code{iconify-frame} event
@cindex $B%$%Y%s%H(B@code{iconify-frame}
@cindex @code{iconify-frame}$B%$%Y%s%H(B
@item (iconify-frame (@var{frame}))
@c This kind of event indicates that the user iconified @var{frame} using
@c the window manager.  Its standard definition is @code{ignore}; since the
@c frame has already been iconified, Emacs has no work to do.  The purpose
@c of this event type is so that you can keep track of such events if you
@c want to.
$B$3$N<o$N%$%Y%s%H$O!"(B
$B%&%#%s%I%&%^%M!<%8%c$rMQ$$$F%f!<%6!<$,%U%l!<%`(B@var{frame}$B$r(B
$B%"%$%3%s2=$7$?$3$H$rI=$9!#(B
$B$3$l$KBP$9$kI8=`Dj5A$O(B@code{ignore}$B$G$"$k!#(B
$B$H$$$&$N$O!"%U%l!<%`$O$9$G$K%"%$%3%s$K$J$C$F$$$k$N$G!"(B
Emacs$B$,9T$&$3$H$O$J$K$b$J$$$+$i$G$"$k!#(B
$B$3$N%$%Y%s%H7?$NL\E*$O!"(B
$BI,MW$J$i$P$=$N<o$N%$%Y%s%H$rFI<T$,DI@W$G$-$k$h$&$K$7$F$*$/$3$H$G$"$k!#(B

@c @cindex @code{make-frame-visible} event
@cindex $B%$%Y%s%H(B@code{make-frame-visible}
@cindex @code{make-frame-visible}$B%$%Y%s%H(B
@item (make-frame-visible (@var{frame}))
@c This kind of event indicates that the user deiconified @var{frame} using
@c the window manager.  Its standard definition is @code{ignore}; since the
@c frame has already been made visible, Emacs has no work to do.
$B$3$N<o$N%$%Y%s%H$O!"(B
$B%&%#%s%I%&%^%M!<%8%c$rMQ$$$F%f!<%6!<$,%"%$%3%s2=$7$?%U%l!<%`(B@var{frame}$B$r(B
$B3+$$$?$3$H$rI=$9!#(B
$B$3$l$KBP$9$kI8=`Dj5A$O(B@code{ignore}$B$G$"$k!#(B
$B$H$$$&$N$O!"%U%l!<%`$O$9$G$K8+$($k$h$&$K$J$C$F$$$k$N$G!"(B
Emacs$B$,9T$&$3$H$O$J$K$b$J$$$+$i$G$"$k!#(B

@c @cindex @code{mouse-wheel} event
@cindex $B%$%Y%s%H(B@code{mouse-wheel}
@cindex @code{mouse-wheel}$B%$%Y%s%H(B
@item (mouse-wheel @var{position} @var{delta})
@c This kind of event is generated by moving a wheel on a mouse (such as
@c the MS Intellimouse).  Its effect is typically a kind of scroll or zoom.
$B$3$N<o$N%$%Y%s%H$O!"(B
$B!J(BMS$B%$%s%F%j%^%&%9$J$I$N!K%^%&%9$N%[%$!<%k$rF0$+$9$H@8@.$5$l$k!#(B
$B$=$NE57?E*$J8z2L$O%9%/%m!<%k$d%:!<%_%s%0$G$"$k!#(B

@c The element @var{delta} describes the amount and direction of the wheel
@c rotation.  Its absolute value is the number of increments by which the
@c wheel was rotated.  A negative @var{delta} indicates that the wheel was
@c rotated backwards, towards the user, and a positive @var{delta}
@c indicates that the wheel was rotated forward, away from the user.
$BMWAG(B@var{delta}$B$O%[%$!<%k$N2sE>J}8~$H2sE>NL$G$"$k!#(B
$B$=$N@dBPCM$O%[%$!<%k$r2s$9$4$H$KA}2C$9$k?t$G$"$k!#(B
$BIi$N(B@var{delta}$B$O!"5UE>!"$D$^$j!"%f!<%6!<$X6aIU$/J}8~$X$N2sE>$rI=$7!"(B
$B@5$N(B@var{delta}$B$O!"=gE>!"$D$^$j!"%f!<%6!<$+$i1s$6$+$kJ}8~$X$N2sE>$rI=$9!#(B

@c The element @var{position} is a list describing the position of the
@c event, in the same format as used in a mouse-click event.
$BMWAG(B@var{position}$B$O%$%Y%s%H$NH/@80LCV$rI=$7!"(B
$B%^%&%9%/%j%C%/%$%Y%s%H$G;H$o$l$k7A<0$HF1$8$G$"$k!#(B

@c This kind of event is generated only on some kinds of systems.
$B$3$N<o$N%$%Y%s%H$O!"$"$k<o$N%7%9%F%`$G$N$_@8@.$5$l$k!#(B

@c @cindex @code{drag-n-drop} event
@cindex $B%$%Y%s%H(B@code{drag-n-drop}
@cindex @code{drag-n-drop}$B%$%Y%s%H(B
@item (drag-n-drop @var{position} @var{files})
@c This kind of event is generated when a group of files is
@c selected in an application outside of Emacs, and then dragged and
@c dropped onto an Emacs frame.
$B$3$N<o$N%$%Y%s%H$O!"(B
Emacs$B$N30B&$N%"%W%j%1!<%7%g%s$G0l72$N%U%!%$%k$rA*Br$7!"(B
$B$=$l$i$r(BEmacs$B$N%U%l!<%`$K%I%i%C%0!u%I%m%C%W$7$?$H$-$K@8@.$5$l$k!#(B

@c The element @var{position} is a list describing the position of the
@c event, in the same format as used in a mouse-click event, and
@c @var{files} is the list of file names that were dragged and dropped.
@c The usual way to handle this event is by visiting these files.
$BMWAG(B@var{position}$B$O%$%Y%s%H$NH/@80LCV$rI=$7!"(B
$B%^%&%9%/%j%C%/%$%Y%s%H$G;H$o$l$k7A<0$HF1$8$G$"$j!"(B
$BMWAG(B@var{files}$B$O%I%i%C%0!u%I%m%C%W$5$l$?%U%!%$%kL>$N%j%9%H$G$"$k!#(B
$B$3$N%$%Y%s%H$r07$&DL>o$N=hM}$O!"$=$l$i$N%U%!%$%k$rK,Ld$9$k$3$H$G$"$k!#(B

@c This kind of event is generated, at present, only on some kinds of
@c systems.
$B8=>u$G$O!"$3$N<o$N%$%Y%s%H$O!"$"$k<o$N%7%9%F%`$G$N$_@8@.$5$l$k!#(B
@end table

@c   If one of these events arrives in the middle of a key sequence---that
@c is, after a prefix key---then Emacs reorders the events so that this
@c event comes either before or after the multi-event key sequence, not
@c within it.
$B$3$l$i$N%$%Y%s%H$,%-!<Ns$NESCf!"$D$^$j!"(B
$B%W%l%U%#%C%/%9%-!<$N$&$7$m$K8=$l$k$H!"(B
$BJ#?t%$%Y%s%H$N%-!<Ns$N$^$($+$&$7$m$KEv3:%$%Y%s%H$r0\F0$7!"(B
$BESCf$K$O8=$l$J$$$h$&$K(BEmacs$B$O%$%Y%s%H$N=g=x$rJB$SBX$($^$9!#(B

@node Event Examples
@c @subsection Event Examples
@subsection $B%$%Y%s%H$NNc(B

@c If the user presses and releases the left mouse button over the same
@c location, that generates a sequence of events like this:
$B%f!<%6!<$,F1$8>l=j$G%^%&%9$N:8%\%?%s$r2!$72<$2$F$+$iN%$9$H!"(B
$B$D$.$N$h$&$J%$%Y%s%HNs$,@8@.$5$l$^$9!#(B

@smallexample
(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
@end smallexample

@c While holding the control key down, the user might hold down the
@c second mouse button, and drag the mouse from one line to the next.
@c That produces two events, as shown here:
$B%3%s%H%m!<%k%-!<$r2!$72<$2$?>uBV$G!"(B
$B%f!<%6!<$,%^%&%9$N(B2$BHVL\$N%\%?%s$r2!$72<$2!"(B
$B%^%&%9$r$D$.$N9T$X%I%i%C%0$9$k$H!"$D$.$N$h$&$J(B2$B$D$N%$%Y%s%H$,@8@.$5$l$^$9!#(B

@smallexample
(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
@end smallexample

@c While holding down the meta and shift keys, the user might press the
@c second mouse button on the window's mode line, and then drag the mouse
@c into another window.  That produces a pair of events like these:
$B%a%?%-!<$H%7%U%H%-!<$r2!$72<$2$?>uBV$G!"(B
$B%f!<%6!<$,%^%&%9$N(B2$BHVL\$N%\%?%s$r%&%#%s%I%&$N%b!<%I9T$G2!$72<$2!"(B
$B%^%&%9$rJL$N%&%#%s%I%&$X%I%i%C%0$9$k$H!"(B
$B$D$.$N$h$&$J(B2$B$D$N%$%Y%s%H$,@8@.$5$l$^$9!#(B

@smallexample
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                   -453816))
@end smallexample

@node Classifying Events
@c @subsection Classifying Events
@subsection $B%$%Y%s%H$NJ,N`(B
@c @cindex event type
@cindex $B%$%Y%s%H7?(B

@c   Every event has an @dfn{event type}, which classifies the event for
@c key binding purposes.  For a keyboard event, the event type equals the
@c event value; thus, the event type for a character is the character, and
@c the event type for a function key symbol is the symbol itself.  For
@c events that are lists, the event type is the symbol in the @sc{car} of
@c the list.  Thus, the event type is always a symbol or a character.
$B3F%$%Y%s%H$K$O(B@dfn{$B%$%Y%s%H7?(B}$B!J(Bevent type$B!K$,$"$C$F!"(B
$B%-!<%P%$%s%G%#%s%0=hM}$N$?$a$K%$%Y%s%H$rJ,N`$7$^$9!#(B
$B%-!<%\!<%I%$%Y%s%H$G$O!"%$%Y%s%H7?$O%$%Y%s%H$NCM$KEy$7$$$G$9!#(B
$B$7$?$,$C$F!"J8;z$KBP$9$k%$%Y%s%H7?$OJ8;z$G$"$j!"(B
$B%U%!%s%/%7%g%s%-!<$KBP$9$k%$%Y%s%H7?$O%7%s%\%k$=$N$b$N$G$9!#(B
$B%j%9%H$G$"$k%$%Y%s%H$G$O!"%$%Y%s%H7?$O%j%9%H$N(B@sc{car}$B$K$"$k%7%s%\%k$G$9!#(B
$B$7$?$,$C$F!"%$%Y%s%H7?$O$D$M$K%7%s%\%k$+J8;z$G$9!#(B

@c   Two events of the same type are equivalent where key bindings are
@c concerned; thus, they always run the same command.  That does not
@c necessarily mean they do the same things, however, as some commands look
@c at the whole event to decide what to do.  For example, some commands use
@c the location of a mouse event to decide where in the buffer to act.
$B%$%Y%s%H7?$,F1$8$G$"$k%$%Y%s%H$O!"%-!<%P%$%s%G%#%s%0$K4X$9$k8B$jF1$8$G$9!#(B
$B$D$^$j!"$=$l$i$OF1$8%3%^%s%I$r<B9T$7$^$9!#(B
$B$7$+$7!"$3$l$O!"$=$l$i$,I,$:$7$bF1$8$3$H$r9T$&$H$$$&0UL#$G$O$"$j$^$;$s!#(B
$B%$%Y%s%HA4BN$rD4$Y$F$J$K$r9T$&$+$r7hDj$9$k%3%^%s%I$b$"$j$^$9!#(B
$B$?$H$($P!"%^%&%9%$%Y%s%H$N@85/0LCV$r;H$C$F!"(B
$B%P%C%U%!$N$I$NItJ,$r=hM}$9$k$+$r7h$a$k%3%^%s%I$b$"$j$^$9!#(B

@c   Sometimes broader classifications of events are useful.  For example,
@c you might want to ask whether an event involved the @key{META} key,
@c regardless of which other key or mouse button was used.
$B%$%Y%s%H$r$*$*$^$+$KJ,N`$9$k$HM-MQ$J>l9g$b$"$j$^$9!#(B
$B$?$H$($P!"B>$N=$>~%-!<$d%^%&%9%\%?%s$K$O4X78$J$7$K!"(B
@key{META}$B%-!<$,;H$o$l$F$$$k%$%Y%s%H$+$I$&$+D4$Y$?$$$3$H$,$"$k$G$7$g$&!#(B

@c   The functions @code{event-modifiers} and @code{event-basic-type} are
@c provided to get such information conveniently.
$B4X?t(B@code{event-modifiers}$B$d(B@code{event-basic-type}$B$O!"(B
$B$=$N$h$&$J>pJs$rJXMx$KM?$($k$?$a$N$b$N$G$9!#(B

@defun event-modifiers event
@c This function returns a list of the modifiers that @var{event} has.  The
@c modifiers are symbols; they include @code{shift}, @code{control},
@c @code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
@c the modifiers list of a mouse event symbol always contains one of
@c @code{click}, @code{drag}, and @code{down}.
$B$3$N4X?t$O!"(B@var{event}$B$K$"$k=$>~;R$N%j%9%H$rJV$9!#(B
$B=$>~;R$O%7%s%\%k$G$"$j!"(B@code{shift}$B!"(B@code{control}$B!"(B
@code{meta}$B!"(B@code{alt}$B!"(B@code{hyper}$B!"(B@code{super}$B$G$"$k!#(B
$B$5$i$K!"%^%&%9%$%Y%s%H%7%s%\%k$N=$>~;R%j%9%H$K$O!"(B
$BI,$:!"(B@code{click}$B!"(B@code{drag}$B!"(B@code{down}$B$N(B1$B$D$,4^$^$l$k!#(B

@c The argument @var{event} may be an entire event object, or just an event
@c type.
$B0z?t(B@var{event}$B$O!"%$%Y%s%H%*%V%8%'%/%HA4BN$G$"$k$+!"C1$J$k%$%Y%s%H7?$G$"$k!#(B

@c Here are some examples:
$BNc$r<($9!#(B

@example
(event-modifiers ?a)
     @result{} nil
(event-modifiers ?\C-a)
     @result{} (control)
(event-modifiers ?\C-%)
     @result{} (control)
(event-modifiers ?\C-\S-a)
     @result{} (control shift)
(event-modifiers 'f5)
     @result{} nil
(event-modifiers 's-f5)
     @result{} (super)
(event-modifiers 'M-S-f5)
     @result{} (meta shift)
(event-modifiers 'mouse-1)
     @result{} (click)
(event-modifiers 'down-mouse-1)
     @result{} (down)
@end example

@c The modifiers list for a click event explicitly contains @code{click},
@c but the event symbol name itself does not contain @samp{click}.
$B%/%j%C%/%$%Y%s%H$KBP$9$k=$>~;R%j%9%H$K$O(B@code{click}$B$,L@<(E*$K4^$^$l$k$,!"(B
$B%$%Y%s%H%7%s%\%k$NL>A0<+BN$K$O(B@samp{click}$B$O4^$^$l$J$$!#(B
@end defun

@defun event-basic-type event
@c This function returns the key or mouse button that @var{event}
@c describes, with all modifiers removed.  For example:
$B$3$N4X?t$O!"(B@var{event}$B$K$"$k%-!<$d%^%&%9%\%?%s$rJV$9!#(B
$B$?$H$($P$D$.$N$H$*$j!#(B

@example
(event-basic-type ?a)
     @result{} 97
(event-basic-type ?A)
     @result{} 97
(event-basic-type ?\C-a)
     @result{} 97
(event-basic-type ?\C-\S-a)
     @result{} 97
(event-basic-type 'f5)
     @result{} f5
(event-basic-type 's-f5)
     @result{} f5
(event-basic-type 'M-S-f5)
     @result{} f5
(event-basic-type 'down-mouse-1)
     @result{} mouse-1
@end example
@end defun

@defun mouse-movement-p object
@c This function returns non-@code{nil} if @var{object} is a mouse movement
@c event.
$B$3$N4X?t$O!"(B@var{object}$B$,%^%&%90\F0$N%$%Y%s%H$J$i$P(B@code{nil}$B0J30$rJV$9!#(B
@end defun

@defun event-convert-list list
@c This function converts a list of modifier names and a basic event type
@c to an event type which specifies all of them.  For example,
$B$3$N4X?t$O!"=$>~;RL>$H4pK\%$%Y%s%H7?$N%j%9%H$r(B
$B$=$l$i$,<($9%$%Y%s%H7?$KJQ49$9$k!#(B
$B$?$H$($P$D$.$N$H$*$j!#(B

@example
(event-convert-list '(control ?a))
     @result{} 1
(event-convert-list '(control meta ?a))
     @result{} -134217727
(event-convert-list '(control super f1))
     @result{} C-s-f1
@end example
@end defun

@node Accessing Events
@c @subsection Accessing Events
@subsection $B%$%Y%s%H$N;2>H(B

@c   This section describes convenient functions for accessing the data in
@c a mouse button or motion event.
$BK\@a$G$O!"%^%&%9%\%?%s%$%Y%s%H$d%b!<%7%g%s%$%Y%s%HFb$N%G!<%?$r(B
$B;2>H$9$k$?$a$NJXMx$J4X?t$K$D$$$F=R$Y$^$9!#(B

@c   These two functions return the starting or ending position of a
@c mouse-button event, as a list of this form:
$B$D$.$N(B2$B$D$N4X?t$O!"0J2<$N7A<0$N%j%9%H$G$"$k%^%&%9%\%?%s%$%Y%s%H$N(B
$B3+;O0LCV$d=*N;0LCV$rJV$7$^$9!#(B

@example
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
@end example

@defun event-start event
@c This returns the starting position of @var{event}.
$B%$%Y%s%H(B@var{event}$B$N3+;O0LCV$rJV$9!#(B

@c If @var{event} is a click or button-down event, this returns the
@c location of the event.  If @var{event} is a drag event, this returns the
@c drag's starting position.
@var{event}$B$,%/%j%C%/%$%Y%s%H$d%\%?%s2!$72<$2%$%Y%s%H$G$"$k$H!"(B
$B%$%Y%s%H$N0LCV$rJV$9!#(B
@var{event}$B$,%I%i%C%0%$%Y%s%H$G$"$k$H!"%I%i%C%0$N3+;O0LCV$rJV$9!#(B
@end defun

@defun event-end event
@c This returns the ending position of @var{event}.
$B%$%Y%s%H(B@var{event}$B$N=*N;0LCV$rJV$9!#(B

@c If @var{event} is a drag event, this returns the position where the user
@c released the mouse button.  If @var{event} is a click or button-down
@c event, the value is actually the starting position, which is the only
@c position such events have.
@var{event}$B$,%I%i%C%0%$%Y%s%H$G$"$k$H!"(B
$B%f!<%6!<$,%^%&%9%\%?%s$rN%$7$?$H$-$N0LCV$rJV$9!#(B
@var{event}$B$,%/%j%C%/%$%Y%s%H$+%\%?%s2!$72<$2%$%Y%s%H$G$"$k$H!"(B
$B<B:]$NCM$O3+;O0LCV$G$"$j!"(B
$B$=$N<o$N%$%Y%s%H$K$"$kM#0l$N0LCV>pJs$G$"$k!#(B
@end defun

@c   These five functions take a position list as described above, and
@c return various parts of it.
$B$D$.$N(B5$B$D$N4X?t$O!">e$K=R$Y$?0LCV>pJs$N%j%9%H$r0z?t$H$7$F!"(B
$B$=$N$5$^$6$^$JItJ,$rJV$9!#(B

@defun posn-window position
@c Return the window that @var{position} is in.
@var{position}$BFb$N%&%#%s%I%&$rJV$9!#(B
@end defun

@defun posn-point position
@c Return the buffer position in @var{position}.  This is an integer.
@var{position}$B$N%P%C%U%!Fb0LCV$rJV$9!#(B
$B$3$l$O@0?t$G$"$k!#(B
@end defun

@defun posn-x-y position
@c Return the pixel-based x and y coordinates in @var{position}, as a cons
@c cell @code{(@var{x} . @var{y})}.
@var{position}$BFb$N%T%/%;%kC10L$N(Bxy$B:BI8$r(B
$B%3%s%9%;%k(B@code{(@var{x} . @var{y})}$B$H$7$FJV$9!#(B
@end defun

@defun posn-col-row position
@c Return the row and column (in units of characters) of @var{position}, as
@c a cons cell @code{(@var{col} . @var{row})}.  These are computed from the
@c @var{x} and @var{y} values actually found in @var{position}.
@var{position}$B$N!JJ8;zC10L$N!K9T!J(Brow$B!K$H%3%i%`!J(Bcol$B!K$N:BI8$r(B
$B%3%s%9%;%k(B@code{(@var{col} . @var{row})}$B$H$7$FJV$9!#(B
$B$3$l$i$O<B:]$K$O(B@var{position}$BFb$N(B@var{x}$B$H(B@var{y}$B$NCM$+$i7W;;$5$l$k!#(B
@end defun

@defun posn-timestamp position
@c Return the timestamp in @var{position}.
@var{position}$BFb$N;~9o>pJs$rJV$9!#(B
@end defun

@c   These functions are useful for decoding scroll bar events.
$B$D$.$N4X?t$O%9%/%m!<%k%P!<$G$N%$%Y%s%H$r2rFI$9$k$N$KJXMx$G$9!#(B

@defun scroll-bar-event-ratio event
@c This function returns the fractional vertical position of a scroll bar
@c event within the scroll bar.  The value is a cons cell
@c @code{(@var{portion} . @var{whole})} containing two integers whose ratio
@c is the fractional position.
$B%9%/%m!<%k%P!<Fb$G$N%$%Y%s%H$+$i!"%9%/%m!<%k%P!<$KBP$9$k=DJ}8~$N0LCV$rJV$9!#(B
$B$=$NCM$O(B2$B$D$N@0?t$r4^$`%3%s%9%;%k(B@code{(@var{portion} . @var{whole})}$B$G$"$j!"(B
$B$=$NHf$O0LCV$N3d9g$rI=$9!#(B
@end defun

@defun scroll-bar-scale ratio total
@c This function multiplies (in effect) @var{ratio} by @var{total},
@c rounding the result to an integer.  The argument @var{ratio} is not a
@c number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
@c value returned by @code{scroll-bar-event-ratio}.
$B$3$N4X?t$O!J<B<AE*$K$O!K(B@var{ratio}$B$K(B@var{total}$B$r3]$1!"(B
$B7k2L$r@0?t$K4]$a$k!#(B
$B0z?t(B@var{ratio}$B$O?t$G$O$J$/(B@code{(@var{num} . @var{denom})}$B$G$"$j!"(B
$BE57?E*$K$O(B@code{scroll-bar-event-ratio}$B$,JV$9CM$G$"$k!#(B

@c This function is handy for scaling a position on a scroll bar into a
@c buffer position.  Here's how to do that:
$B$3$N4X?t$O%9%/%m!<%k%P!<Fb$G$N0LCV$r(B
$B%P%C%U%!Fb$G$N0LCV$X49;;$9$k$N$KJXMx$G$"$k!#(B
$B$D$.$N$h$&$K9T$&!#(B

@example
(+ (point-min)
   (scroll-bar-scale
      (posn-x-y (event-start event))
      (- (point-max) (point-min))))
@end example

@c Recall that scroll bar events have two integers forming a ratio, in place
@c of a pair of x and y coordinates.
$B%9%/%m!<%k%P!<Fb$G$N%$%Y%s%H$K$O!"(B
xy$B:BI8$N$+$o$j$KHf$rI=$9(B2$B$D$N@0?t$,$"$k$3$H$KCm0U!#(B
@end defun

@node Strings of Events
@c @subsection Putting Keyboard Events in Strings
@subsection $B%-!<%\!<%I%$%Y%s%H$rJ8;zNs$GJ];}$9$k(B

@c   In most of the places where strings are used, we conceptualize the
@c string as containing text characters---the same kind of characters found
@c in buffers or files.  Occasionally Lisp programs use strings that
@c conceptually contain keyboard characters; for example, they may be key
@c sequences or keyboard macro definitions.  However, storing keyboard
@c characters in a string is a complex matter, for reasons of historical
@c compatibility, and it is not always possible.
$BJ8;zNs$,;H$o$l$k$[$H$s$I$N>lLL$G$O!"(B
$BJ8;zNs$K$O%F%-%9%HJ8;z!"$D$^$j!"(B
$B%P%C%U%!$d%U%!%$%k$K$"$kJ8;z$HF1$8<oN`$N$b$N$,F~$C$F$$$k$H9M$($F$$$^$9!#(B
$BJ8;zNs$K$O%-!<%\!<%IJ8;z$,F~$C$F$$$k$H$_$J$7$F;H$&(BLisp$B%W%m%0%i%`$b$"$j$^$9!#(B
$B$?$H$($P!"J8;zNs$K$O!"%-!<Ns$d%-!<%\!<%I%^%/%m$NDj5A$,F~$C$F$$$k$N$G$9!#(B
$B$7$+$7!"%-!<%\!<%IJ8;z$rJ8;zNs$KJ];}$9$k$N$OJ#;($G$"$j!"(B
$B$=$l$ONr;KE*$J8_49@-$rJ]$D$?$a$K$9$k$N$G$"$j!"(B
$B$^$?!"$D$M$K2DG=$H$O8B$j$^$;$s!#(B

@c   We recommend that new programs avoid dealing with these complexities
@c by not storing keyboard events in strings.  Here is how to do that:
$B?7$7$$%W%m%0%i%`$G$O!"%-!<%\!<%I%$%Y%s%H$rJ8;zNs$KJ];}$7$J$$$G!"(B
$B$3$N$h$&$JJ#;($5$rHr$1$k$h$&$K?d>)$7$^$9!#(B
$B$D$.$N$h$&$K$7$^$9!#(B

@itemize @bullet
@item
@c Use vectors instead of strings for key sequences, when you plan to use
@c them for anything other than as arguments to @code{lookup-key} and
@c @code{define-key}.  For example, you can use
@c @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
@c @code{this-command-keys-vector} instead of @code{this-command-keys}.
$B%-!<Ns$KBP$7$F$O!"$=$l$i$r(B@code{lookup-key}$B$d(B@code{define-key}$B$KBP$9$k(B
$B0z?t0J30$K$b;H$&$D$b$j$J$i$P!"J8;zNs$N$+$o$j$K%Y%/%H%k$r;H$&!#(B
$B$?$H$($P!"(B@code{read-key-sequence}$B$N$+$o$j$K(B@code{read-key-sequence-vector}$B$r(B
@code{this-command-keys}$B$N$+$o$j$K(B@code{this-command-keys-vector}$B$r;H$&!#(B

@item
@c Use vectors to write key sequence constants containing meta characters,
@c even when passing them directly to @code{define-key}.
$B%a%?J8;z$r4^$`%-!<Ns$O!"(B
$B$=$l$i$r(B@code{define-key}$B$KD>@\EO$9>l9g$G$"$C$F$b!"%Y%/%H%k$G=q$/!#(B

@item
@c When you have to look at the contents of a key sequence that might be a
@c string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
@c first, to convert it to a list.
$BJ8;zNs$G$"$k2DG=@-$,$"$k%-!<Ns$NFbMF$rD4$Y$k$H$-$K$O!"(B
@code{listify-key-sequence}$B!J(B@pxref{Event Input Misc}$B!K$r;H$C$F!"(B
$B$=$l$r%j%9%H$KJQ49$7$F$*$/!#(B
@end itemize

@c   The complexities stem from the modifier bits that keyboard input
@c characters can include.  Aside from the Meta modifier, none of these
@c modifier bits can be included in a string, and the Meta modifier is
@c allowed only in special cases.
$BJ#;($5$N860x$O!"%-!<%\!<%IF~NO$K4^$^$l$k=$>~%S%C%H$K$"$j$^$9!#(B
$B%a%?=$>~;R0J30$N=$>~%S%C%H$rJ8;zNs$KF~$l$k$3$H$OIT2DG=$G$"$j!"(B
$B%a%?=$>~;R$OFCJL$J>l9g$H$7$FM#0l5v$5$l$F$$$k$N$G$9!#(B

@c   The earliest GNU Emacs versions represented meta characters as codes
@c in the range of 128 to 255.  At that time, the basic character codes
@c ranged from 0 to 127, so all keyboard character codes did fit in a
@c string.  Many Lisp programs used @samp{\M-} in string constants to stand
@c for meta characters, especially in arguments to @code{define-key} and
@c similar functions, and key sequences and sequences of events were always
@c represented as strings.
$B=i4|$N(BGNU Emacs$B$G$O!"%a%?J8;z$r(B128$B$+$i(B255$B$NHO0O$N%3!<%I$GI=8=$7$F$$$^$7$?!#(B
$B$=$NEv;~!"4pK\J8;z%3!<%I$O(B0$B$+$i(B127$B$G$7$?$+$i!"(B
$B%-!<%\!<%IJ8;z$N$9$Y$F$N%3!<%I$OJ8;zNs$K<}$^$C$?$N$G$9!#(B
$BB?$/$N(BLisp$B%W%m%0%i%`$G%a%?J8;z$rI=$9$?$a$KJ8;zNsDj?tFb$G(B@samp{\M-}$B$r;H$$!"(B
$BFC$K!"(B@code{define-key}$B$dN`;w$N4X?t$KBP$9$k0z?t$K;H$o$l!"(B
$B%-!<Ns$d%$%Y%s%HNs$O$D$M$KJ8;zNs$GI=8=$5$l$F$$$^$7$?!#(B

@c   When we added support for larger basic character codes beyond 127, and
@c additional modifier bits, we had to change the representation of meta
@c characters.  Now the flag that represents the Meta modifier in a
@c character is
127$B$rD6$($kBg$-$J4pK\J8;z%3!<%I$HDI2C$N=$>~%S%C%H$r07$($k$h$&$K$7$?$H$-!"(B
$B%a%?J8;z$NI=8=J}K!$rJQ99$;$6$k$r$($^$;$s$G$7$?!#(B
$B8=:_!"%a%?=$>~;R$rI=$9J8;zFb$N%S%C%H$O(B
@tex
$2^{27}$
@end tex
@ifinfo
2**27
@end ifinfo
@c and such numbers cannot be included in a string.
$B$G$"$j!"$=$N$h$&$J?t$rJ8;zNs$KF~$l$k$3$H$O$G$-$^$;$s!#(B

@c   To support programs with @samp{\M-} in string constants, there are
@c special rules for including certain meta characters in a string.
@c Here are the rules for interpreting a string as a sequence of input
@c characters:
$BJ8;zNsDj?t$G(B@samp{\M-}$B$r;H$C$F$$$k%W%m%0%i%`$r07$($k$h$&$K!"(B
$BJ8;zNs$K%a%?J8;z$rF~$l$k$?$a$NFCJL$J5,B'$,$"$j$^$9!#(B
$B0J2<$O!"J8;zNs$rF~NOJ8;z$NNs$H$7$F2r<a$9$k$?$a$N5,B'$G$9!#(B

@itemize @bullet
@item
@c If the keyboard character value is in the range of 0 to 127, it can go
@c in the string unchanged.
$B%-!<%\!<%IJ8;z$NCM$,(B0$B$+$i(B127$B$NHO0O$K$"$l$P!"(B
$BL5JQ99$GJ8;zNs$KF~$l$k!#(B

@item
@c The meta variants of those characters, with codes in the range of
$B%3!<%I$,(B
@tex
$2^{27}$
@end tex
@ifinfo
2**27
@end ifinfo
@c to
$B$+$i(B
@tex
$2^{27} + 127$,
@end tex
@ifinfo
2**27+127,
@end ifinfo
@c can also go in the string, but you must change their
@c numeric values.  You must set the
$B$NHO0O$K$"$k$3$l$i$NJ8;z$N%a%?JQ<o$OJ8;zNs$KF~$l$i$l$k$,!"(B
$B$=$l$i$N?tCM$rJQ99$9$kI,MW$,$"$k!#(B
$B%S%C%H(B
@tex
$2^{27}$
@end tex
@ifinfo
2**27
@end ifinfo
$B$N$+$o$j$K(B
@tex
$2^{7}$
@end tex
@ifinfo
2**7
@end ifinfo
@c bit instead of the
$B%S%C%H$KJQ99$7!"(B
@c @tex
@c $2^{27}$
@c @end tex
@c @ifinfo
@c 2**27
@c @end ifinfo
@c bit, resulting in a value between 128 and 255.  Only a unibyte string
@c can include these codes.
128$B$+$i(B255$B$NHO0O$NCM$K$9$k!#(B
$B%f%K%P%$%HJ8;zNs$@$1$K$3$l$i$N%3!<%I$rF~$l$i$l$k!#(B

@item
@c Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
256$B0J>e$NHs(B@sc{ASCII}$BJ8;z$O%^%k%A%P%$%HJ8;zNs$@$1$KF~$l$i$l$k!#(B

@item
@c Other keyboard character events cannot fit in a string.  This includes
@c keyboard events in the range of 128 to 255.
$B$=$NB>$N%-!<%\!<%IJ8;z%$%Y%s%H$OJ8;zNs$K<}$a$i$l$J$$!#(B
$B$3$l$K$O!"(B128$B$+$i(B255$B$NHO0O$N%-!<%\!<%I%$%Y%s%H$b4^$`!#(B
@end itemize

@c   Functions such as @code{read-key-sequence} that construct strings of
@c keyboard input characters follow these rules: they construct vectors
@c instead of strings, when the events won't fit in a string.
$B%-!<%\!<%IF~NOJ8;z$NJ8;zNs$r:n$k(B@code{read-key-sequence}$B$J$I$N4X?t$O(B
$B$D$.$N5,B'$K=>$$$^$9!#(B
$B$D$^$j!"J8;zNs$K<}$^$i$J$$%$%Y%s%H$G$"$k$H$-$K$O!"(B
$BJ8;zNs$N$+$o$j$K%Y%/%H%k$r:n$j$^$9!#(B

@c   When you use the read syntax @samp{\M-} in a string, it produces a
@c code in the range of 128 to 255---the same code that you get if you
@c modify the corresponding keyboard event to put it in the string.  Thus,
@c meta events in strings work consistently regardless of how they get into
@c the strings.
$BFI<T$,J8;zNs$G(B@samp{\M-}$B$NF~NO9=J8$r;H$&$H!"(B
$B$=$l$i$O(B128$B$+$i(B255$B$NHO0O$N%3!<%I$K$J$j$^$9!#(B
$BBP1~$9$k%-!<%\!<%I%$%Y%s%H$rJ8;zNs$KJ]B8$9$k$h$&$KJQ99$7$?$H$-$KF@$i$l$k(B
$B%3!<%I$HF1$8$G$9!#(B
$B$7$?$,$C$F!"J8;zNsFb$N%a%?%$%Y%s%H$O!"$=$l$i$,$I$N$h$&$KJ8;zNs$K(B
$B<}$a$i$l$?$+$K4X$o$i$:!"@09g@-$N$"$kF0:n$r$7$^$9!#(B

@c   However, most programs would do well to avoid these issues by
@c following the recommendations at the beginning of this section.
$B$7$+$7!"K\@a$N$O$8$a$K=R$Y$??d>)J}K!$K=>$C$F$3$l$i$N$3$H$,$i$rHr$1$k$[$&$,!"(B
$B$[$H$s$I$N%W%m%0%i%`$O$h$j$h$/F0:n$9$k$G$7$g$&!#(B

@node Reading Input
@c @section Reading Input
@section $BF~NO$NFI$_<h$j(B

@c   The editor command loop reads key sequences using the function
@c @code{read-key-sequence}, which uses @code{read-event}.  These and other
@c functions for event input are also available for use in Lisp programs.
@c See also @code{momentary-string-display} in @ref{Temporary Displays},
@c and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
@c functions and variables for controlling terminal input modes and
@c debugging terminal input.  @xref{Translating Input}, for features you
@c can use for translating or modifying input events while reading them.
$B%(%G%#%?%3%^%s%I%k!<%W$O!"(B
$B4X?t(B@code{read-key-sequence}$B$r;H$C$F%-!<Ns$rFI$_<h$j$^$9!#(B
$B$J$*!"4X?t(B@code{read-key-sequence}$B$O4X?t(B@code{read-event}$B$r;H$$$^$9!#(B
$B$3$l$i$d%$%Y%s%HF~NO$r07$&B>$N4X?t$O!"(BLisp$B%W%m%0%i%`$+$i$b;H$($^$9!#(B
@ref{Temporary Displays}$B$N(B@code{momentary-string-display}$B!"(B
$B$*$h$S!"(B@ref{Waiting}$B$N(B@code{sit-for}$B$r;2>H$7$F$/$@$5$$!#(B
$BC<Kv$NF~NO%b!<%I$N@)8f$dC<KvF~NO$N%G%P%C%0$K4X$9$k4X?t$dJQ?t$K$D$$$F$O!"(B
@xref{Terminal Input}$B!#(B
$BF~NO%$%Y%s%H$rFI$`$H$-$K$=$l$i$rJQ49$7$?$j=$@5$9$k5!G=$K$D$$$F$O!"(B
@xref{Translating Input}$B!#(B

@c   For higher-level input facilities, see @ref{Minibuffers}.
$B>e0L%l%Y%k$NF~NO5!G=$K$D$$$F$O!"(B@ref{Minibuffers}$B$r;2>H$7$F$/$@$5$$!#(B

@menu
* Key Sequence Input::		How to read one key sequence.
* Reading One Event::		How to read just one event.
* Quoted Character Input::	Asking the user to specify a character.
* Event Input Misc::    	How to reread or throw away input events.
@end menu

@node Key Sequence Input
@c @subsection Key Sequence Input
@subsection $B%-!<Ns$NF~NO(B
@c @cindex key sequence input
@cindex $B%-!<Ns$NF~NO(B

@c   The command loop reads input a key sequence at a time, by calling
@c @code{read-key-sequence}.  Lisp programs can also call this function;
@c for example, @code{describe-key} uses it to read the key to describe.
$B%3%^%s%I%k!<%W$O!"(B@code{read-key-sequence}$B$r8F$V$3$H$G(B
$B%-!<Ns$NF~NO$rFI$_<h$j$^$9!#(B
Lisp$B%W%m%0%i%`$+$i$3$N4X?t$r8F$S=P$7$F$b$h$/!"(B
$B$?$H$($P!"(B@code{describe-key}$B$O!"(B
$B@bL@BP>]$H$9$k%-!<$rFI$`$?$a$K$3$N4X?t$r;H$$$^$9!#(B

@defun read-key-sequence prompt
@c @cindex key sequence
@cindex $B%-!<Ns(B
@c This function reads a key sequence and returns it as a string or
@c vector.  It keeps reading events until it has accumulated a complete key
@c sequence; that is, enough to specify a non-prefix command using the
@c currently active keymaps.
$B$3$N4X?t$O!"%-!<Ns$rFI$_<h$jJ8;zNs$+%Y%/%H%k$H$7$FJV$9!#(B
$B40A4$J%-!<Ns$r<}=8$7=*$($k$^$G!"(B
$B$D$^$j!"8=:_3h@-$J%-!<%^%C%W$K$*$$$F!"Hs%W%l%U%#%C%/%9%3%^%s%I$r(B
$B;XDj$9$k$N$K==J,$K$J$k$^$G!"%$%Y%s%H$rFI$_B3$1$k!#(B

@c If the events are all characters and all can fit in a string, then
@c @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
@c Otherwise, it returns a vector, since a vector can hold all kinds of
@c events---characters, symbols, and lists.  The elements of the string or
@c vector are the events in the key sequence.
$B%$%Y%s%H$,$9$Y$FJ8;z$G$"$j!"$+$D!"$=$l$i$,J8;zNs$K<}$^$k$J$i$P!"(B
@code{read-key-sequence}$B$OJ8;zNs!J(B@pxref{Strings of Events}$B!K$rJV$9!#(B
$B$5$b$J$1$l$P!"%Y%/%H%k$rJV$9!#(B
$B%Y%/%H%k$J$i$P!"G$0U$N<oN`$N%$%Y%s%H!"$D$^$j!"(B
$BJ8;z!"%7%s%\%k!"%j%9%H$rJ];}$G$-$k$+$i$G$"$k!#(B
$BJ8;zNs$d%Y%/%H%k$NMWAG$O!"%-!<Ns$N%$%Y%s%H$G$"$k!#(B

@c The argument @var{prompt} is either a string to be displayed in the echo
@c area as a prompt, or @code{nil}, meaning not to display a prompt.
$B0z?t(B@var{prompt}$B$O!"%W%m%s%W%H$H$7$F%(%3!<NN0h$KI=<($9$kJ8;zNs$G$"$k$+!"(B
$B$"$k$$$O!"%W%m%s%W%H$rI=<($7$J$$$3$H$r0UL#$9$k(B@code{nil}$B$G$"$k!#(B

@c In the example below, the prompt @samp{?} is displayed in the echo area,
@c and the user types @kbd{C-x C-f}.
$B0J2<$NNc$G$O!"%W%m%s%W%H(B@samp{?}$B$,%(%3!<NN0h$KI=<($5$l!"(B
$B%f!<%6!<$O(B@kbd{C-x C-f}$B$HBG$D!#(B

@example
(read-key-sequence "?")

@group
---------- Echo Area ----------
?@kbd{C-x C-f}
---------- Echo Area ----------

     @result{} "^X^F"
@end group
@end example

@c The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
@c typed while reading with this function works like any other character,
@c and does not set @code{quit-flag}.  @xref{Quitting}.
$B4X?t(B@code{read-key-sequence}$B$OCfCG$rM^;_$9$k!#(B
$B$3$N4X?t$,F0:nCf$K(B@kbd{C-g}$B$rBG$C$F$b!"B>$NJ8;z$HF1MM$K07$$!"(B
@code{quit-flag}$B$r@_Dj$7$J$$!#(B
@pxref{Quitting}$B!#(B
@end defun

@defun read-key-sequence-vector prompt
@c This is like @code{read-key-sequence} except that it always
@c returns the key sequence as a vector, never as a string.
@c @xref{Strings of Events}.
$B$3$l$O(B@code{read-key-sequence}$B$HF1MM$G$"$k$,!"(B
$B$D$M$K%Y%/%H%k$H$7$F%-!<Ns$rJV$7!"J8;zNs$H$7$F$O$1$C$7$FJV$5$J$$!#(B
@pxref{Strings of Events}$B!#(B
@end defun

@c @cindex upper case key sequence
@c @cindex downcasing in @code{lookup-key}
@cindex $BBgJ8;z$N%-!<Ns(B
@cindex @code{lookup-key}$B$K$*$1$k>.J8;z$X$NJQ49(B
@c If an input character is an upper-case letter and has no key binding,
@c but its lower-case equivalent has one, then @code{read-key-sequence}
@c converts the character to lower case.  Note that @code{lookup-key} does
@c not perform case conversion in this way.
$BF~NOJ8;z$,BgJ8;z$G$"$C$F!"$=$l$i$K%-!<%P%$%s%G%#%s%0$,$J$$$H$-!"(B
$BBP1~$9$k>.J8;z$K%-!<%P%$%s%G%#%s%0$,$"$l$P!"(B
@code{read-key-sequence}$B$OJ8;z$r>.J8;z$KJQ49$7$^$9!#(B
@code{lookup-key}$B$O$3$N$h$&$JJQ49$r9T$o$J$$$3$H$KCm0U$7$F$/$@$5$$!#(B

@c The function @code{read-key-sequence} also transforms some mouse events.
@c It converts unbound drag events into click events, and discards unbound
@c button-down events entirely.  It also reshuffles focus events and
@c miscellaneous window events so that they never appear in a key sequence
@c with any other events.
$B4X?t(B@code{read-key-sequence}$B$O!"$"$k<o$N%^%&%9%$%Y%s%H$bJQ49$7$^$9!#(B
$B%P%$%s%G%#%s%0$N$J$$%I%i%C%0%$%Y%s%H$r%/%j%C%/%$%Y%s%H$KJQ49$7$?$j!"(B
$B%P%$%s%G%#%s%0$N$J$$%\%?%s2!$72<$2%$%Y%s%H$r40A4$KL5;k$7$^$9!#(B
$B$5$i$K!"%U%)!<%+%9%$%Y%s%H$H$=$NB>$N%&%#%s%I%&%$%Y%s%H$rJB$SBX$($F!"(B
$B$=$l$i$,B>$N%$%Y%s%H$N%-!<Ns$NESCf$K8=$l$J$$$h$&$K$7$^$9!#(B

@c When mouse events occur in special parts of a window, such as a mode
@c line or a scroll bar, the event type shows nothing special---it is the
@c same symbol that would normally represent that combination of mouse
@c button and modifier keys.  The information about the window part is kept
@c elsewhere in the event---in the coordinates.  But
@c @code{read-key-sequence} translates this information into imaginary
@c ``prefix keys'', all of which are symbols: @code{mode-line},
@c @code{vertical-line}, @code{horizontal-scroll-bar} and
@c @code{vertical-scroll-bar}.  You can define meanings for mouse clicks in
@c special window parts by defining key sequences using these imaginary
@c prefix keys.
$B%^%&%9%$%Y%s%H$,!"%b!<%I9T$d%9%/%m!<%k%P!<$J$I$N%&%#%s%I%&$NFCJL$JItJ,$G(B
$B@85/$7$F$b!"FCJL$J%$%Y%s%H7?$O$J$/!"%^%&%9%\%?%s$d=$>~%-!<$N(B
$BAH$_9g$o$;$rIaDL$I$*$j$KI=$7$?%7%s%\%k$G$9!#(B
$B%&%#%s%I%&$N$I$NItJ,$+$K4X$9$k>pJs$O!"(B
$B%$%Y%s%HFb$NJL$NItJ,!"$D$^$j!":BI8$KF~$C$F$$$^$9!#(B
$B$7$+$7!"(B@code{read-key-sequence}$B$O!"$=$N>pJs$r(B
$B%7%s%\%k(B@code{mode-line}$B!"(B@code{vertical-line}$B!"(B@code{horizontal-scroll-bar}$B!"(B
@code{vertical-scroll-bar}$B$rMQ$$$?2>A[E*$J!X%W%l%U%#%C%/%9%-!<!Y$KJQ49$7$^$9!#(B
$B%&%#%s%I%&$NFCJL$JItJ,$K$*$1$k%^%&%9%/%j%C%/$N0UL#$O!"(B
$B$3$l$i$N2>A[E*$J%W%l%U%#%C%/%9%-!<$rMQ$$$F%-!<Ns$rDj5A$9$k$3$H$G(B
$BDj5A$G$-$^$9!#(B

@c For example, if you call @code{read-key-sequence} and then click the
@c mouse on the window's mode line, you get two events, like this:
$B$?$H$($P!"(B@code{read-key-sequence}$B$r8F$S=P$7$F$+$i!"(B
$B%&%#%s%I%&$N%b!<%I9T$G%/%j%C%/$9$k$H!"(B
$B$D$.$N$h$&$J(B2$B$D$N%$%Y%s%H$rF@$^$9!#(B

@example
(read-key-sequence "Click on the mode line: ")
     @result{} [mode-line
         (mouse-1
          (#<window 6 on NEWS> mode-line
           (40 . 63) 5959987))]
@end example

@defvar num-input-keys
@c @c Emacs 19 feature
@c This variable's value is the number of key sequences processed so far in
@c this Emacs session.  This includes key sequences read from the terminal
@c and key sequences read from keyboard macros being executed.
$B$3$NJQ?t$NCM$O!"8=:_$N(BEmacs$B%;%C%7%g%s$K$*$$$F!"(B
$B$3$l$^$G$K=hM}$5$l$?%-!<Ns$N8D?t$G$"$k!#(B
$B$3$l$K$O!"C<Kv$+$iFI$_<h$C$?%-!<Ns!"$*$h$S!"(B
$B<B9T$7$?%-!<%\!<%I%^%/%m$+$iFI$_<h$C$?%-!<Ns$,4^$^$l$k!#(B
@end defvar

@defvar num-nonmacro-input-events
@tindex num-nonmacro-input-events
@c This variable holds the total number of input events received so far
@c from the terminal---not counting those generated by keyboard macros.
$B$3$NJQ?t$O!"C<Kv$+$i$3$l$^$G$K<u$1<h$C$?F~NO%$%Y%s%H$NAm8D?t$rJ];}$9$k!#(B
$B%-!<%\!<%I%^%/%m$G@8@.$5$l$?$b$N$O4^$^$J$$!#(B
@end defvar

@node Reading One Event
@c @subsection Reading One Event
@subsection $BC10l%$%Y%s%H$NFI$_<h$j(B

@c   The lowest level functions for command input are those that read a
@c single event.
$B%3%^%s%IF~NOMQ$N:GDc%l%Y%k$N4X?t$O!"C10l%$%Y%s%H$rFI$_<h$k4X?t$G$9!#(B

@defun read-event &optional prompt suppress-input-method
@c This function reads and returns the next event of command input, waiting
@c if necessary until an event is available.  Events can come directly from
@c the user or from a keyboard macro.
$B$3$N4X?t$O!"I,MW$J$i$P%$%Y%s%H$NE~Ce$rBT$C$F!"(B
$B%3%^%s%IF~NO$N$D$.$N%$%Y%s%H$rFI$_<h$C$FJV$9!#(B
$B%$%Y%s%H$O!"%f!<%6!<$+!J<B9TCf$N!K%-!<%\!<%I%^%/%m$+$iD>@\F@$k!#(B

@c If @var{prompt} is non-@code{nil}, it should be a string to display in
@c the echo area as a prompt.  Otherwise, @code{read-event} does not
@c display any message to indicate it is waiting for input; instead, it
@c prompts by echoing: it displays descriptions of the events that led to
@c or were read by the current command.  @xref{The Echo Area}.
@var{prompt}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$l$O%W%m%s%W%H$H$7$F%(%3!<NN0h$KI=<($5$l$kJ8;zNs$G$"$k$3$H!#(B
$B$5$b$J$1$l$P!"(B@code{read-event}$B$O(B
$BF~NOBT$A$G$"$k$3$H$r<($9%a%C%;!<%8$rI=<($;$:$K!"(B
$B$=$N$+$o$j$K!"8=:_$N%3%^%s%I$r<B9T$9$k$K;j$C$?%$%Y%s%H$d(B
$B8=:_$N%3%^%s%I$,FI$_<h$C$?%$%Y%s%H$r%W%m%s%W%H$H$7$FI=<($9$k!#(B
@pxref{The Echo Area}$B!#(B

@c If @var{suppress-input-method} is non-@code{nil}, then the current input
@c method is disabled for reading this event.  If you want to read an event
@c without input-method processing, always do it this way; don't try binding
@c @code{input-method-function} (see below).
@var{suppress-input-method}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N%$%Y%s%H$NFI$_<h$j$K4X$7$F$O8=:_$NF~NOJ}<0$r;H$o$J$$!#(B
$BF~NOJ}<0$N=hM}$r$;$:$K%$%Y%s%H$rFI$_$?$$$H$-$K$O!"(B
$B$D$M$K$3$N$h$&$K$9$k$3$H!#(B
@code{input-method-function}$B$rB+G{$7$F$O$J$i$J$$!J2<5-;2>H!K!#(B

@c If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
@c moves the cursor temporarily to the echo area, to the end of any message
@c displayed there.  Otherwise @code{read-event} does not move the cursor.
$BJQ?t(B@code{cursor-in-echo-area}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{read-event}$B$O!"%(%3!<NN0h$KI=<($5$l$?%a%C%;!<%8$NKvHx$K(B
$B%+!<%=%k$r0l;~E*$K0\F0$9$k!#(B
$B$5$b$J$1$l$P!"(B@code{read-event}$B$O%+!<%=%k$r0\F0$7$J$$!#(B

@c If @code{read-event} gets an event that is defined as a help character, in
@c some cases @code{read-event} processes the event directly without
@c returning.  @xref{Help Functions}.  Certain other events, called
@c @dfn{special events}, are also processed directly within
@c @code{read-event} (@pxref{Special Events}).
@code{read-event}$B$,%X%k%WJ8;z$HDj5A$5$l$?%$%Y%s%H$r<u$1<h$k$H!"(B
$B$=$l$rJV$5$:$K(B@code{read-event}$B$,%$%Y%s%H$rD>@\=hM}$7$F$7$^$&>l9g$,$"$k!#(B
@pxref{Help Functions}$B!#(B
@dfn{$BFC<l%$%Y%s%H(B}$B!J(Bspecial event$B!K$H8F$P$l$kB>$N%$%Y%s%H$b(B
@code{read-event}$B$,D>@\=hM}$9$k!J(B@pxref{Special Events}$B!K!#(B

@c Here is what happens if you call @code{read-event} and then press the
@c right-arrow function key:
@code{read-event}$B$r8F$s$G1&Lp0u$N%U%!%s%/%7%g%s%-!<$r2!$9$H$D$.$N$h$&$K$J$k!#(B

@example
@group
(read-event)
     @result{} right
@end group
@end example
@end defun

@defun read-char
@c This function reads and returns a character of command input.  It
@c discards any events that are not characters, until it gets a character.
$B$3$N4X?t$O%3%^%s%IF~NO$NJ8;z$rFI$_<h$j$=$l$rJV$9!#(B
$BJ8;z$rF@$k$^$G!"J8;z0J30$N%$%Y%s%H$O$9$Y$FGK4~$9$k!#(B

@c In the first example, the user types the character @kbd{1} (@sc{ASCII}
@c code 49).  The second example shows a keyboard macro definition that
@c calls @code{read-char} from the minibuffer using @code{eval-expression}.
@c @code{read-char} reads the keyboard macro's very next character, which
@c is @kbd{1}.  Then @code{eval-expression} displays its return value in
@c the echo area.
$B:G=i$NNc$G$O!"%f!<%6!<$OJ8;z(B@kbd{1}$B!J(B@sc{ASCII}$B%3!<%I(B49$B!K$rBG$D!#(B
2$BHVL\$NNc$O!"(B@code{eval-expression}$B$r;H$C$F(B
$B%_%K%P%C%U%!$+$i(B@code{read-char}$B$r8F$S=P$9%-!<%\!<%I%^%/%m$NDj5A$G$"$k!#(B
@code{read-char}$B$O%-!<%\!<%I%^%/%m$ND>8e$NJ8;z!"$D$^$j!"(B@kbd{1}$B$rFI$`!#(B
$B$=$7$F!"(B@code{eval-expression}$B$O$=$NLa$jCM$r%(%3!<NN0h$KI=<($9$k!#(B

@example
@group
(read-char)
     @result{} 49
@end group

@group
@c ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
;; @r{$B$3$l$rI>2A$9$k$?$a$KFI<T$O(B@kbd{M-:}$B$r;H$&$H2>Dj$9$k(B}
(symbol-function 'foo)
     @result{} "^[:(read-char)^M1"
@end group
@group
(execute-kbd-macro 'foo)
     @print{} 49
     @result{} nil
@end group
@end example
@end defun

@c   @code{read-event} also invokes the current input method, if any.  If
@c the value of @code{input-method-function} is non-@code{nil}, it should
@c be a function; when @code{read-event} reads a printing character
@c (including @key{SPC}) with no modifier bits, it calls that function,
@c passing the event as an argument.
@code{read-event}$B$O!"$"$l$P8=:_$NF~NOJ}<0$b5/F0$7$^$9!#(B
@code{input-method-function}$B$,(B@code{nil}$B0J30$G$"$l$P!"(B
$B$=$l$O4X?t$G$"$k$O$:$G$9!#(B
@code{read-event}$B$,=$>~%S%C%H$N$J$$!J(B@key{SPC}$B$r4^$`!K0u;zJ8;z$rFI$_<h$k$H!"(B
$B0z?t$H$7$F%$%Y%s%H$rEO$7$F$=$N4X?t$r8F$S=P$7$^$9!#(B

@defvar input-method-function
@c If this is non-@code{nil}, its value specifies the current input method
@c function.
$B$3$l$,(B@code{nil}$B0J30$G$"$k$H!"$=$NCM$O8=:_$NF~NOJ}<04X?t$r;XDj$9$k!#(B

@c @strong{Note:} Don't bind this variable with @code{let}.  It is often
@c buffer-local, and if you bind it around reading input (which is exactly
@c when you @emph{would} bind it), switching buffers asynchronously while
@c Emacs is waiting will cause the value to be restored in the wrong
@c buffer.
@strong{$BCm0U!'(B}@code{ }
$B$3$NJQ?t$r(B@code{let}$B$GB+G{$7$J$$$3$H!#(B
$B$3$NJQ?t$O$7$P$7$P%P%C%U%!%m!<%+%k$G$"$j!"(B
$BF~NO$rFI$`<~0O$GB+G{$9$k$H!JFI<T$,$3$l$r$b$C$H$bB+G{(B@emph{$B$7$=$&$J(B}$B$H$3$m!K!"(B
Emacs$B$,F~NO$rBT$C$F$$$k$H$-$K%P%C%U%!$,HsF14|$K@Z$jBX$o$k$H!"(B
$B8m$C$?%P%C%U%!$KCM$rI|85$7$F$7$^$&$3$H$,$"$k!#(B
@end defvar

@c   The input method function should return a list of events which should
@c be used as input.  (If the list is @code{nil}, that means there is no
@c input, so @code{read-event} waits for another event.)  These events are
@c processed before the events in @code{unread-command-events}.  Events
@c returned by the input method function are not passed to the input method
@c function again, even if they are printing characters with no modifier
@c bits.
$BF~NOJ}<04X?t$O!"F~NO$H$7$F;H$o$l$k%$%Y%s%H$N%j%9%H$rJV$9$Y$-$G$9!#(B
$B!J%j%9%H$,(B@code{nil}$B$G$"$k$HF~NO$,$J$+$C$?$3$H$r0UL#$7!"(B
@code{read-event}$B$OJL$N%$%Y%s%H$rBT$D!#!K(B
$B$3$l$i$N%$%Y%s%H$O!"(B
@code{unread-command-events}$BFb$N%$%Y%s%H$h$j$^$($K=hM}$5$l$^$9!#(B
$BF~NOJ}<04X?t$,JV$7$?%$%Y%s%H$O!"$=$l$i$,=$>~%S%C%H$,$J$$0u;zJ8;z$G$"$C$F$b!"(B
$BF~NOJ}<04X?t$K:FEYEO$5$l$k$3$H$O$"$j$^$;$s!#(B

@c   If the input method function calls @code{read-event} or
@c @code{read-key-sequence}, it should bind @code{input-method-function} to
@c @code{nil} first, to prevent recursion.
$BF~NOJ}<04X?t$,(B@code{read-event}$B$d(B@code{read-key-sequence}$B$r8F$S=P$9$H$-$K$O!"(B
@code{input-method-function}$B$r(B@code{nil}$B$KB+G{$7$F(B
$B:F5"8F$S=P$7$rKI$0$Y$-$G$9!#(B

@c   The input method function is not called when reading the second and
@c subsequent event of a key sequence.  Thus, these characters are not
@c subject to input method processing.  It is usually a good idea for the
@c input method processing to test the values of
@c @code{overriding-local-map} and @code{overriding-terminal-local-map}; if
@c either of these variables is non-@code{nil}, the input method should put
@c its argument into a list and return that list with no further
@c processing.
$B%-!<Ns$N(B2$BHVL\0J9_$N%$%Y%s%H$rFI$`$H$-$K$O!"F~NOJ}<04X?t$r8F$S=P$7$^$;$s!#(B
$B$7$?$,$C$F!"$=$l$i$NJ8;z$O!"F~NOJ}<0=hM}$NBP>]$G$O$"$j$^$;$s!#(B
$BF~NOJ}<0$N=hM}$G$O!"(B
@code{overriding-local-map}$B$H(B@code{overriding-terminal-local-map}$B$NCM$r(B
$B8!::$9$k$N$,$h$$$G$9!#(B
$B$3$l$i$NJQ?t$N$$$:$l$+$,(B@code{nil}$B0J30$G$"$k$H$-$K$O!"(B
$BF~NOJ}<0$G$O$=$N0z?t$r%j%9%H$KF~$l!"(B
$B$=$l0J>e=hM}$;$:$K$=$N%j%9%H$rJV$9$Y$-$G$9!#(B

@node Quoted Character Input
@c @subsection Quoted Character Input
@subsection $B%/%)!<%H$7$?J8;z$NF~NO(B
@c @cindex quoted character input
@cindex $B%/%)!<%H$7$?J8;z$NF~NO(B

@c   You can use the function @code{read-quoted-char} to ask the user to
@c specify a character, and allow the user to specify a control or meta
@c character conveniently, either literally or as an octal character code.
@c The command @code{quoted-insert} uses this function.
$B%f!<%6!<$KJ8;zF~NO$rB%$7$F!"%3%s%H%m!<%kJ8;z$d%a%?J8;z$r(B
$BJ8;z$=$N$b$N$dJ8;z$N(B8$B?J?t%3!<%I$G<j7Z$KF~NO$G$-$k$h$&$K$9$k$K$O!"(B
$B4X?t(B@code{read-quoted-char}$B$r;H$$$^$9!#(B
$B%3%^%s%I(B@code{quoted-insert}$B$O!"$3$N4X?t$r;H$C$F$$$^$9!#(B

@defun read-quoted-char &optional prompt
@c @cindex octal character input
@c @cindex control characters, reading
@c @cindex nonprinting characters, reading
@cindex 8$B?J?t;zJ8;zF~NO(B
@cindex $B%3%s%H%m!<%kJ8;z!"FI$_<h$j(B
@cindex $BHs0u;zJ8;z!"FI$_<h$j(B
@c This function is like @code{read-char}, except that if the first
@c character read is an octal digit (0-7), it reads any number of octal
@c digits (but stopping if a non-octal digit is found), and returns the
@c character represented by that numeric character code.
$B$3$N4X?t$O(B@code{read-char}$B$K;w$F$$$k$,!"(B
$B:G=i$KFI$s$@J8;z$,(B8$B?J?t;zJ8;z!J(B0-7$B!K$G$"$k$H!"(B
$BG$0U8D?t$N(B8$B?J?t;zJ8;z$rFI$_<h$j!J(B8$B?J?t;zJ8;z0J30$,8=$l$k$H;_$a$k!K!"(B
$B$=$N?tCM$NJ8;z%3!<%I$,I=$9J8;z$rJV$9!#(B

@c Quitting is suppressed when the first character is read, so that the
@c user can enter a @kbd{C-g}.  @xref{Quitting}.
$B:G=i$NJ8;z$rFI$`$HCfCG$rM^@)$9$k$N$G!"(B
$B%f!<%6!<$O(B@kbd{C-g}$B$rF~NO$G$-$k!#(B
@pxref{Quitting}$B!#(B

@c If @var{prompt} is supplied, it specifies a string for prompting the
@c user.  The prompt string is always displayed in the echo area, followed
@c by a single @samp{-}.
@var{prompt}$B$rM?$($k$H!"$=$l$O%f!<%6!<$X$N%W%m%s%W%H$rI=$9J8;zNs$r;XDj$9$k!#(B
$B%W%m%s%W%HJ8;zNs$O$D$M$K%(%3!<NN0h$KI=<($5$l!"$"$H$K(B@samp{-}$B$,B3$/!#(B

@c In the following example, the user types in the octal number 177 (which
@c is 127 in decimal).
$B$D$.$NNc$G$O!"%f!<%6!<$O(B8$B?J?t(B177$B!J(B10$B?J?t$G$O(B127$B!K$rBG$D!#(B

@example
(read-quoted-char "What character")

@group
---------- Echo Area ----------
What character-@kbd{177}
---------- Echo Area ----------

     @result{} 127
@end group
@end example
@end defun

@need 2000
@node Event Input Misc
@c @subsection Miscellaneous Event Input Features
@subsection $B$=$NB>$N%$%Y%s%HF~NO5!G=(B

@c This section describes how to ``peek ahead'' at events without using
@c them up, how to check for pending input, and how to discard pending
@c input.  See also the function @code{read-passwd} (@pxref{Reading a
@c Password}).
$BK\@a$G$O!"%$%Y%s%H$r=hM}$;$:$K!X$^$($b$C$FGA$-8+!Y$9$kJ}K!!"(B
$B=hM}BT$A$NF~NO$NM-L5$N8!::J}K!!"=hM}BT$A$NF~NO$NGK4~J}K!$K$D$$$F=R$Y$^$9!#(B
$B4X?t(B@code{read-passwd}$B$b;2>H$7$F$/$@$5$$!J(B@pxref{Reading a Password}$B!K!#(B

@defvar unread-command-events
@c @cindex next input
@c @cindex peeking at input
@cindex $B$D$.$NF~NO(B
@cindex $BF~NO$rGA$-8+$k(B
@c This variable holds a list of events waiting to be read as command
@c input.  The events are used in the order they appear in the list, and
@c removed one by one as they are used.
$B$3$NJQ?t$O!"%3%^%s%IF~NO$H$7$FFI$^$l$k$3$H$r(B
$BBT$C$F$$$k%$%Y%s%H$N%j%9%H$rJ];}$9$k!#(B
$B%$%Y%s%H$O%j%9%H$K8=$l$k=g$K;H$o$l!";H$o$l$k$H(B1$B$D(B1$B$D<h$j=|$+$l$k!#(B

@c The variable is needed because in some cases a function reads an event
@c and then decides not to use it.  Storing the event in this variable
@c causes it to be processed normally, by the command loop or by the
@c functions to read command input.
$B4X?t$G%$%Y%s%H$rFI$s$@$"$H$K$=$l$r;H$o$J$$>lLL$,$"$k$?$a!"(B
$B$3$NJQ?t$,I,MW$K$J$k!#(B
$B$3$NJQ?t$K%$%Y%s%H$rJ]B8$9$k$H!"(B
$B%3%^%s%I%k!<%W$d%3%^%s%IF~NO$rFI$`4X?t$K$h$C$FDL>o$I$*$j=hM}$5$l$k!#(B

@c @cindex prefix argument unreading
@cindex $BA0CV0z?t$NFI$_La$7(B
@c For example, the function that implements numeric prefix arguments reads
@c any number of digits.  When it finds a non-digit event, it must unread
@c the event so that it can be read normally by the command loop.
@c Likewise, incremental search uses this feature to unread events with no 
@c special meaning in a search, because these events should exit the search
@c and then execute normally.
$B$?$H$($P!"?tCMA0CV0z?t$r<B8=$9$k4X?t$O!"G$0U8D?t$N?t;zJ8;z$rFI$_<h$k!#(B
$B?t;zJ8;z$G$J$$%$%Y%s%H$r$_$D$1$?$i!"$=$N%$%Y%s%H$rFI$_La$7$F!"(B
$B%3%^%s%I%k!<%W$,DL>o$I$*$j$KFI$a$k$h$&$K$9$kI,MW$,$"$k!#(B
$BF1MM$K!"%$%s%/%j%a%s%?%k%5!<%A$G$O!"$3$N5!G=$r;H$C$F(B
$BC5:w$K$*$$$F$O0UL#$r;}$?$J$$%$%Y%s%H$rFI$_La$9!#(B
$B$J$<$J$i!"$=$N$h$&$J%$%Y%s%H$OC5:w$r=*N;$5$;!"(B
$BDL>o$I$*$j<B9T$5$l$kI,MW$,$"$k$+$i$G$"$k!#(B

@c The reliable and easy way to extract events from a key sequence so as to
@c put them in @code{unread-command-events} is to use
@c @code{listify-key-sequence} (@pxref{Strings of Events}).
@code{unread-command-events}$B$KF~$l$i$l$k$h$&$K(B
$B%-!<Ns$+$i%$%Y%s%H$r3N<B$K4JC1$K<h$j=P$9J}K!$O(B
@code{listify-key-sequence}$B$r;H$&$3$H$G$"$k!J(B@pxref{Strings of Events}$B!K!#(B

@c Normally you add events to the front of this list, so that the events
@c most recently unread will be reread first.
$B$b$C$H$b:G6a$KFI$_La$7$?%$%Y%s%H$,:G=i$K:FEYFI$^$l$k$h$&$K!"(B
$BIaDL$O$3$N%j%9%H$N@hF,$K%$%Y%s%H$rDI2C$9$k!#(B
@end defvar

@defun listify-key-sequence key
@c This function converts the string or vector @var{key} to a list of
@c individual events, which you can put in @code{unread-command-events}.
$B$3$N4X?t$O!"J8;zNs$d%Y%/%H%k$G$"$k(B@var{key}$B$r8D!9$N%$%Y%s%H$N%j%9%H$KJQ49$9$k!#(B
$B$3$N7k2L$O(B@code{unread-command-events}$B$KF~$l$i$l$k!#(B
@end defun

@defvar unread-command-char
@c This variable holds a character to be read as command input.
@c A value of -1 means ``empty''.
$B$3$NJQ?t$O!"%3%^%s%IF~NO$H$7$FFI$^$l$kJ8;z$rJ];}$9$k!#(B
$BCM!V(B-1$B!W$O!"!X6u!Y$r0UL#$9$k!#(B

@c This variable is mostly obsolete now that you can use
@c @code{unread-command-events} instead; it exists only to support programs
@c written for Emacs versions 18 and earlier.
$B$3$NJQ?t$O$[$H$s$IGQ$l$F$*$j!"(B
$B$+$o$j$K(B@code{unread-command-events}$B$r;H$&$Y$-$G$"$k!#(B
Emacs 18$BHG0JA08~$1$K=q$+$l$?%W%m%0%i%`$r07$&$?$a$@$1$KB8:_$9$k!#(B
@end defvar

@defun input-pending-p
@c @cindex waiting for command key input
@cindex $B%3%^%s%I%-!<F~NO$rBT$D(B
@c This function determines whether any command input is currently
@c available to be read.  It returns immediately, with value @code{t} if
@c there is available input, @code{nil} otherwise.  On rare occasions it
@c may return @code{t} when no input is available.
$B$3$N4X?t$O!"8=:_!"%3%^%s%IF~NO$,$"$k$+$I$&$+$rD4$Y$k!#(B
$B$?$@$A$KJV$k$,!"F~NO$,$"$l$PCM(B@code{t}$B$r!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$BF~NO$,$J$$$N$K(B@code{t}$B$rJV$9$3$H$,5)$K$"$k!#(B
@end defun

@defvar last-input-event
@defvarx last-input-char
@c This variable records the last terminal input event read, whether
@c as part of a command or explicitly by a Lisp program.
$B$3$NJQ?t$O!"%3%^%s%I$N0lIt$H$7$F!"$"$k$$$O!"(BLisp$B%W%m%0%i%`$,L@<(E*$K(B
$BFI$_<h$C$?:G8e$NC<KvF~NO%$%Y%s%H$r5-O?$9$k!#(B

@c In the example below, the Lisp program reads the character @kbd{1},
@c @sc{ASCII} code 49.  It becomes the value of @code{last-input-event},
@c while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
@c this expression) remains the value of @code{last-command-event}.
$B0J2<$NNc$G!"(BLisp$B%W%m%0%i%`$OJ8;z(B@kbd{1}$B!J(B@sc{ASCII}$B%3!<%I(B49$B!K$rFI$`!#(B
$B$=$l$,(B@code{last-input-event}$B$NCM$K$J$k$,!"(B
$B!J$3$N<0$rI>2A$9$k%3%^%s%I$O(B@kbd{C-x C-e}$B$H2>Dj$9$k$N$G!K(B
@code{last-command-event}$B$NCM$O(B@kbd{C-e}$B$N$^$^$G$"$k!#(B

@example
@group
(progn (print (read-char))
       (print last-command-event)
       last-input-event)
     @print{} 49
     @print{} 5
     @result{} 49
@end group
@end example

@c The alias @code{last-input-char} exists for compatibility with
@c Emacs version 18.
Emacs 18$BHG$H$N8_49@-$N$?$a$K!"JLL>(B@code{last-input-char}$B$,B8:_$9$k!#(B
@end defvar

@defun discard-input
@c @cindex flush input
@c @cindex discard input
@c @cindex terminate keyboard macro
@cindex $BF~NO$NGK4~(B
@cindex $B%-!<%\!<%I%^%/%m$N=*N;(B
@c This function discards the contents of the terminal input buffer and
@c cancels any keyboard macro that might be in the process of definition.
@c It returns @code{nil}.
$B$3$N4X?t$OC<KvF~NO%P%C%U%!$NFbMF$rGQ4~$7!"(B
$BDj5ACf$N%-!<%\!<%I%^%/%m$r<h$j>C$9!#(B
$B$3$l$O(B@code{nil}$B$rJV$9!#(B

@c In the following example, the user may type a number of characters right
@c after starting the evaluation of the form.  After the @code{sleep-for}
@c finishes sleeping, @code{discard-input} discards any characters typed 
@c during the sleep.
$B0J2<$NNc$G!"%U%)!<%`$rI>2A$7$O$8$a$F$+$i!"%f!<%6!<$O2?J8;z$+BG$D!#(B
@code{sleep-for}$B$,BT5!$r=*$($k$H!"(B
@code{discard-input}$B$OBT5!Cf$KBG$?$l$?J8;z$r$9$Y$FGK4~$9$k!#(B

@example
(progn (sleep-for 2)
       (discard-input))
     @result{} nil
@end example
@end defun

@node Special Events
@c @section Special Events
@section $BFC<l%$%Y%s%H(B

@c @cindex special events
@cindex $BFC<l%$%Y%s%H(B
@c Special events are handled at a very low level---as soon as they are
@c read.  The @code{read-event} function processes these events itself, and
@c never returns them.
$BFC<l%$%Y%s%H$O!"FI$^$l$k$H$?$@$A$KHs>o$KDc%l%Y%k$G=hM}$5$l$^$9!#(B
$B4X?t(B@code{read-event}$B$O$3$l$i$N%$%Y%s%H$r$=$l<+?H$G=hM}$7$F$7$^$$!"(B
$B$=$l$i$rJV$9$3$H$O$"$j$^$;$s!#(B

@c Events that are handled in this way do not echo, they are never grouped
@c into key sequences, and they never appear in the value of
@c @code{last-command-event} or @code{(this-command-keys)}.  They do not
@c discard a numeric argument, they cannot be unread with
@c @code{unread-command-events}, they may not appear in a keyboard macro,
@c and they are not recorded in a keyboard macro while you are defining
@c one.
$B$3$N$h$&$K=hM}$5$l$k%$%Y%s%H$OI=<($5$l$k$3$H$O$J$/!"(B
$B%-!<Ns$KAH$_9~$^$l$k$3$H$b$J$/!"(B
@code{last-command-event}$B$d(B@code{(this-command-keys)}$B$NCM$K(B
$B8=$l$k$3$H$b$"$j$^$;$s!#(B
$BFC<l%$%Y%s%H$,?tCM0z?t$rGK4~$9$k$3$H$O$J$/!"(B
@code{unread-command-events}$B$GFI$_La$9$3$H$O$G$-$^$;$s!#(B
$BFC<l%$%Y%s%H$,%-!<%\!<%I%^%/%m$K8=$l$k$3$H$O$J$/!"(B
$BFI<T$,%-!<%\!<%I%^%/%m$rDj5A$7$F$$$k$H$-$K!"(B
$BFC<l%$%Y%s%H$,%-!<%\!<%I%^%/%m$K5-O?$5$l$k$3$H$O$"$j$^$;$s!#(B

@c These events do, however, appear in @code{last-input-event} immediately
@c after they are read, and this is the way for the event's definition to
@c find the actual event.
$B$7$+$7!"$=$l$i$N%$%Y%s%H$O!"(B
$BFI$^$l$?D>8e$K$O(B@code{last-input-event}$B$K8=$l$^$9$+$i!"(B
$B$3$l$+$i%$%Y%s%H$NDj5A$G<B:]$N%$%Y%s%H$r8+$k$3$H$,$G$-$^$9!#(B

@c The events types @code{iconify-frame}, @code{make-frame-visible} and
@c @code{delete-frame} are normally handled in this way.  The keymap which
@c defines how to handle special events---and which events are special---is
@c in the variable @code{special-event-map} (@pxref{Active Keymaps}).
@code{iconify-frame}$B!"(B@code{make-frame-visible}$B!"(B@code{delete-frame}$B$N(B
$B%$%Y%s%H7?$O!"DL>o$3$N$h$&$K=hM}$5$l$^$9!#(B
$BFC<l%$%Y%s%H$r$I$N$h$&$K=hM}$9$k$+!"(B
$B$I$N%$%Y%s%H$,FC<l%$%Y%s%H$G$"$k$+$rDj5A$9$k(B
$B%-!<%^%C%W$OJQ?t(B@code{special-event-map}$B$K$"$j$^$9!J(B@pxref{Active Keymaps}$B!K!#(B

@node Waiting
@c @section Waiting for Elapsed Time or Input
@section $B;~4VBT$A$HF~NOBT$A(B
@c @cindex pausing
@c @cindex waiting
@cindex $B5Y;_(B
@cindex $BBT5!(B

@c   The wait functions are designed to wait for a certain amount of time
@c to pass or until there is input.  For example, you may wish to pause in
@c the middle of a computation to allow the user time to view the display.
@c @code{sit-for} pauses and updates the screen, and returns immediately if
@c input comes in, while @code{sleep-for} pauses without updating the
@c screen.
$BBT5!4X?t$O!";XDj;~4V7P2a$9$k$+F~NO$,$/$k$^$GBT$D$h$&$K@_7W$7$F$"$j$^$9!#(B
$B$?$H$($P!"%f!<%6!<$KI=<($rD/$a$k;~4V$rM?$($k$?$a$K(B
$B7W;;ESCf$G5Y;_$7$?$$$G$7$g$&!#(B
@code{sit-for}$B$O!"5Y;_$7$F%9%/%j!<%s$r99?7$7!"(B
$BF~NO$,$/$k$H$?$@$A$KLa$j$^$9!#(B
$B0lJ}!"(B@code{sleep-for}$B$O%9%/%j!<%s$r99?7$;$:$K5Y;_$7$^$9!#(B

@defun sit-for seconds &optional millisec nodisp
@c This function performs redisplay (provided there is no pending input
@c from the user), then waits @var{seconds} seconds, or until input is
@c available.  The value is @code{t} if @code{sit-for} waited the full
@c time with no input arriving (see @code{input-pending-p} in @ref{Event 
@c Input Misc}).  Otherwise, the value is @code{nil}.
$B$3$N4X?t$O!J=hM}BT$A$N%f!<%6!<$+$i$NF~NO$,$J$1$l$P!K:FI=<($r9T$$!"(B
@var{seconds}$BIC5Y;_$9$k$+!"F~NO$,$/$k$^$GBT$D!#(B
$BF~NO$,$3$:$K!J(B@ref{Event Input Misc}$B$N(B@code{input-pending-p}$B$r;2>H!K(B
$B;XDj;~4V$@$15Y;_$7$?>l9g$O!"La$jCM$O(B@code{t}$B$G$"$k!#(B
$B$5$b$J$1$l$P!"La$jCM$O(B@code{nil}$B$G$"$k!#(B

@c The argument @var{seconds} need not be an integer.  If it is a floating
@c point number, @code{sit-for} waits for a fractional number of seconds.
@c Some systems support only a whole number of seconds; on these systems,
@c @var{seconds} is rounded down.
$B0z?t(B@var{seconds}$B$O@0?t$G$"$kI,MW$O$J$$!#(B
$B$=$l$,IbF0>.?tE@?t$G$"$k$H!"(B@code{sit-for}$B$OIC$N>.?t$bBT$D!#(B
$BICC10L$7$+07$($J$$%7%9%F%`$b$"$j!"(B
$B$=$N$h$&$J%7%9%F%`$G$O(B@var{seconds}$B$rIC$K@Z$j2<$2$k!#(B

@c The optional argument @var{millisec} specifies an additional waiting
@c period measured in milliseconds.  This adds to the period specified by
@c @var{seconds}.  If the system doesn't support waiting fractions of a
@c second, you get an error if you specify nonzero @var{millisec}.
$B>JN,2DG=$J0z?t(B@var{millisec}$B$O!"%_%jICC10L$NDI2CBT$A;~4V$r;XDj$9$k!#(B
$B$3$l$O(B@var{seconds}$B$G;XDj$7$?;~4V$K2C$($i$l$k!#(B
$BICL$K~$r07$($J$$%7%9%F%`$G$O!"(B
@var{millisec}$B$K(B0$B0J30$r;XDj$9$k$H%(%i!<$K$J$k!#(B

@c @cindex forcing redisplay
@cindex $B:FI=<($N6/@)(B
@c Redisplay is always preempted if input arrives, and does not happen at
@c all if input is available before it starts.  Thus, there is no way to
@c force screen updating if there is pending input; however, if there is no
@c input pending, you can force an update with no delay by using
@c @code{(sit-for 0)}.
$BF~NO$,$/$k$H:FI=<($r$D$M$K<h$j;_$a!"(B
$B:FI=<(3+;O$^$($KF~NO$,$/$k$H!"$$$C$5$$:FI=<($7$J$$!#(B
$B$7$?$,$C$F!"=hM}BT$A$NF~NO$,$"$k$H!":FI=<($r6/@)$9$kJ}K!$O$J$$!#(B
$B$7$+$7!"=hM}BT$A$NF~NO$,$J$1$l$P!"(B@code{(sit-for 0)}$B$G:FI=<($r6/@)$G$-$k!#(B

@c If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
@c redisplay, but it still returns as soon as input is available (or when
@c the timeout elapses).
@var{nodisp}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{sit-for}$B$O:FI=<($O$7$J$$$,!"(B
$BF~NO$,$/$k$H$?$@$A$K!J$"$k$$$O;XDj;~4V$@$17P2a$9$k$H!KLa$k!#(B

@c Iconifying or deiconifying a frame makes @code{sit-for} return, because
@c that generates an event.  @xref{Misc Events}.
$B%U%l!<%`$r%"%$%3%s$K$7$?$j%"%$%3%s$K$7$?%U%l!<%`$r3+$/$H(B
$B%$%Y%s%H$,@8@.$5$l$k$?$a!"(B@code{sit-for}$B$OLa$k!#(B
@pxref{Misc Events}$B!#(B

@c The usual purpose of @code{sit-for} is to give the user time to read
@c text that you display.
@code{sit-for}$B$NIaDL$NL\E*$O!"(B
$BFI<T$,I=<($7$?%F%-%9%H$rFI$`;~4V$r%f!<%6!<$KM?$($k$3$H$G$"$k!#(B
@end defun

@defun sleep-for seconds &optional millisec
@c This function simply pauses for @var{seconds} seconds without updating
@c the display.  It pays no attention to available input.  It returns
@c @code{nil}.
$B$3$N4X?t$OI=<($r99?7$;$:$KC1$K(B@var{seconds}$BIC$@$15Y;_$9$k!#(B
$BF~NO$K$O$$$C$5$$Cm0U$rJ'$o$J$$!#(B
@code{nil}$B$rJV$9!#(B

@c The argument @var{seconds} need not be an integer.  If it is a floating
@c point number, @code{sleep-for} waits for a fractional number of seconds.
@c Some systems support only a whole number of seconds; on these systems,
@c @var{seconds} is rounded down.
$B0z?t(B@var{seconds}$B$O@0?t$G$"$kI,MW$O$J$$!#(B
$B$=$l$,IbF0>.?tE@?t$G$"$k$H!"(B@code{sleep-for}$B$OIC$N>.?t$bBT$D!#(B
$BICC10L$7$+07$($J$$%7%9%F%`$b$"$j!"(B
$B$=$N$h$&$J%7%9%F%`$G$O(B@var{seconds}$B$rIC$K@Z$j2<$2$k!#(B

@c The optional argument @var{millisec} specifies an additional waiting
@c period measured in milliseconds.  This adds to the period specified by
@c @var{seconds}.  If the system doesn't support waiting fractions of a
@c second, you get an error if you specify nonzero @var{millisec}.
$B>JN,2DG=$J0z?t(B@var{millisec}$B$O!"%_%jICC10L$NDI2CBT$A;~4V$r;XDj$9$k!#(B
$B$3$l$O(B@var{seconds}$B$G;XDj$7$?;~4V$K2C$($i$l$k!#(B
$BICL$K~$r07$($J$$%7%9%F%`$G$O!"(B
@var{millisec}$B$K(B0$B0J30$r;XDj$9$k$H%(%i!<$K$J$k!#(B

@c Use @code{sleep-for} when you wish to guarantee a delay.
$BCY1d$rJ]>Z$7$?$$>l9g$K(B@code{sleep-for}$B$r;H$&!#(B
@end defun

@c   @xref{Time of Day}, for functions to get the current time.
$B8=:_;~9o$r<hF@$9$k4X?t$K$D$$$F$O(B@xref{Time of Day}$B!#(B

@node Quitting
@c @section Quitting
@section $BCfCG(B
@cindex @kbd{C-g}
@c @cindex quitting
@cindex $BCfCG(B

@c   Typing @kbd{C-g} while a Lisp function is running causes Emacs to
@c @dfn{quit} whatever it is doing.  This means that control returns to the
@c innermost active command loop.
Lisp$B4X?t$,F0:nCf$K(B@kbd{C-g}$B$rBG$D$H!"(B
Emacs$B$,$J$K$r9T$C$F$$$F$b(B@dfn{$BCfCG(B}$B$r0z$-5/$3$7$^$9!#(B
$B$D$^$j!"$b$C$H$bFbB&$N3h@-$J%3%^%s%I%k!<%W$K@)8f$,La$j$^$9!#(B

@c   Typing @kbd{C-g} while the command loop is waiting for keyboard input
@c does not cause a quit; it acts as an ordinary input character.  In the
@c simplest case, you cannot tell the difference, because @kbd{C-g}
@c normally runs the command @code{keyboard-quit}, whose effect is to quit.
@c However, when @kbd{C-g} follows a prefix key, they combine to form an
@c undefined key.  The effect is to cancel the prefix key as well as any
@c prefix argument.
$B%3%^%s%I%k!<%W$,%-!<%\!<%IF~NO$rBT$C$F$$$k$H$-$K(B@kbd{C-g}$B$rBG$C$F$b!"(B
$BCfCG$r0z$-5/$3$5$:$K!"IaDL$NF~NOJ8;z$H$7$FF0:n$7$^$9!#(B
$B$b$C$H$bC1=c$J>l9g!"(B@kbd{C-g}$B$O%3%^%s%I(B@code{keyboard-quit}$B$r<B9T$7$^$9$,!"(B
$B$=$N8z2L$OCfCG$r0z$-5/$3$9$3$H$G$9$+$i!"FI<T$K$O6hJL$G$-$J$$$O$:$G$9!#(B
$B$7$+$7!"%W%l%U%#%C%/%9%-!<$KB3$1$F(B@kbd{C-g}$B$rBG$D$H!"(B
$B$=$l$i$OAH$_9g$o$5$l$FL$Dj5A%-!<$K$J$j$^$9!#(B
$B$=$N8z2L$O!"A0CV0z?t$r4^$a$F%W%l%U%#%C%/%9%-!<$r<h$j>C$7$^$9!#(B

@c   In the minibuffer, @kbd{C-g} has a different definition: it aborts out
@c of the minibuffer.  This means, in effect, that it exits the minibuffer
@c and then quits.  (Simply quitting would return to the command loop
@c @emph{within} the minibuffer.)  The reason why @kbd{C-g} does not quit
@c directly when the command reader is reading input is so that its meaning
@c can be redefined in the minibuffer in this way.  @kbd{C-g} following a
@c prefix key is not redefined in the minibuffer, and it has its normal
@c effect of canceling the prefix key and prefix argument.  This too
@c would not be possible if @kbd{C-g} always quit directly.
$B%_%K%P%C%U%!$G$O!"(B@kbd{C-g}$B$K$OJL$NDj5A$,$"$C$F!"(B
$B%_%K%P%C%U%!$r6/@)=*N;$5$;$^$9!#(B
$B$D$^$j!"%_%K%P%C%U%!$+$iH4$1=P$FCfCG$7$^$9!#(B
$B!JC1$KCfCG$7$?$N$G$O!"%_%K%P%C%U%!(B@emph{$BFb$G(B}
$B%3%^%s%I%k!<%W$KLa$k$@$1$G$"$k!#!K(B
$B%3%^%s%I%k!<%W$GF~NO$rFI$s$G$$$k$H$-$K(B@kbd{C-g}$B$GD>@\CfCG$7$J$$M}M3$O!"(B
$B$3$N$h$&$K%_%K%P%C%U%!$G$=$N0UL#$r:FDj5A$G$-$k$h$&$K$9$k$?$a$G$9!#(B
$B%_%K%P%C%U%!$G$O!"%W%l%U%#%C%/%9%-!<$KB3$/(B@kbd{C-g}$B$O:FDj5A$7$F$J$/!"(B
$B%W%l%U%#%C%/%9%-!<$HA0CV0z?t$r<h$j>C$9$H$$$&DL>o$N8z2L$r;}$A$^$9!#(B
@kbd{C-g}$B$,$D$M$KD>@\CfCG$9$k$N$G$O!"$3$N$h$&$K$9$k$3$H$5$(IT2DG=$G$9!#(B

@c   When @kbd{C-g} does directly quit, it does so by setting the variable
@c @code{quit-flag} to @code{t}.  Emacs checks this variable at appropriate
@c times and quits if it is not @code{nil}.  Setting @code{quit-flag}
@c non-@code{nil} in any way thus causes a quit.
@kbd{C-g}$B$,D>@\$KCfCG$9$k$H$-$K$O!"(B
$BJQ?t(B@code{quit-flag}$B$K(B@code{t}$B$r@_Dj$7$^$9!#(B
Emacs$B$O$3$NJQ?t$rE,@Z$J$H$-$K8!::$7(B@code{nil}$B$G$J$$$HCfCG$7$^$9!#(B
$B$7$?$,$C$F!"(B@code{quit-flag}$B$K(B@code{nil}$B0J30$r@_Dj$9$k$H(B
$BCfCG$r0z$-5/$3$7$^$9!#(B

@c   At the level of C code, quitting cannot happen just anywhere; only at the
@c special places that check @code{quit-flag}.  The reason for this is
@c that quitting at other places might leave an inconsistency in Emacs's
@c internal state.  Because quitting is delayed until a safe place, quitting 
@c cannot make Emacs crash.
C$B$N%3!<%I$N%l%Y%k$G$O!"$I$3$G$bCfCG$G$-$k$o$1$G$O$"$j$^$;$s!#(B
@code{quit-flag}$B$r8!::$7$F$$$kFCJL$J2U=j$@$1$G$9!#(B
$B$3$N$h$&$K$9$k$N$O!"$=$l0J30$N2U=j$GCfCG$9$k$H(B
Emacs$B$NFbIt>uBV$KL7=b$r$-$?$92DG=@-$,$"$k$+$i$G$9!#(B
$BCfCG$O0BA4$J>l=j$^$G1d4|$5$l$k$N$G!"(B
$BCfCG$K$h$C$F(BEmcas$B$,%/%i%C%7%e$9$k$3$H$O$"$j$^$;$s!#(B

@c   Certain functions such as @code{read-key-sequence} or
@c @code{read-quoted-char} prevent quitting entirely even though they wait
@c for input.  Instead of quitting, @kbd{C-g} serves as the requested
@c input.  In the case of @code{read-key-sequence}, this serves to bring
@c about the special behavior of @kbd{C-g} in the command loop.  In the
@c case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
@c to quote a @kbd{C-g}.  
@code{read-key-sequence}$B$d(B@code{read-quoted-char}$B$J$I$N$"$k<o$N4X?t$O!"(B
$BF~NO$rBT$C$F$$$k>l9g$G$"$C$F$bCfCG$r40A4$KM^@)$7$^$9!#(B
$BCfCG$9$k$+$o$j$K!"(B@kbd{C-g}$B$OF~NO$H$7$FF/$-$^$9!#(B
@code{read-key-sequence}$B$N>l9g!"%3%^%s%I%k!<%W$K$*$$$F(B
@kbd{C-g}$B$NFCJL$J$U$k$^$$$r$b$?$i$7$^$9!#(B
@code{read-quoted-char}$B$N>l9g!"(B
@kbd{C-q}$B$G(B@kbd{C-g}$B$r%/%)!<%H$G$-$k$h$&$K$J$j$^$9!#(B

@c   You can prevent quitting for a portion of a Lisp function by binding
@c the variable @code{inhibit-quit} to a non-@code{nil} value.  Then,
@c although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
@c usual result of this---a quit---is prevented.  Eventually,
@c @code{inhibit-quit} will become @code{nil} again, such as when its
@c binding is unwound at the end of a @code{let} form.  At that time, if
@c @code{quit-flag} is still non-@code{nil}, the requested quit happens
@c immediately.  This behavior is ideal when you wish to make sure that
@c quitting does not happen within a ``critical section'' of the program.
$BJQ?t(B@code{inhibit-quit}$B$K(B@code{nil}$B0J30$NCM$rB+G{$9$k$3$H$G(B
Lisp$B4X?t$N$"$kItJ,$K$*$$$FCfCG$rM^@)$G$-$^$9!#(B
$B$=$&$9$k$H!"(B@kbd{C-g}$B$O$=$l$G$b$$$D$b$I$*$j(B
@code{quit-flag}$B$r(B@code{t}$B$K$7$^$9$,!"(B
$B$=$NDL>o$N7k2L$G$"$kCfCG$OM^@)$5$l$^$9!#(B
$B:G=*E*$K%U%)!<%`(B@code{let}$B$N=*$j$GB+G{$,2r=|$5$l$k$J$I$7$F(B
@code{inhibit-quit}$B$,:FEY(B@code{nil}$B$K$J$j$^$9!#(B
$B$=$N;~E@$G$b(B@code{quit-flag}$B$,(B@code{nil}$B0J30$G$"$k$H(B
$BMW5a$7$?CfCG$,$?$@$A$K5/$3$j$^$9!#(B
$B$3$N$U$k$^$$$O!"%W%m%0%i%`$N!XNW3&NN0h!Y$G$O(B
$BCfCG$,5/$3$i$J$$$3$H$rJ]>Z$9$kM}A[E*$J$b$N$G$9!#(B

@c @cindex @code{read-quoted-char} quitting
@cindex @code{read-quoted-char}$B$NCfCG(B
@c   In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
@c handled in a special way that does not involve quitting.  This is done
@c by reading the input with @code{inhibit-quit} bound to @code{t}, and
@c setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
@c becomes @code{nil} again.  This excerpt from the definition of
@c @code{read-quoted-char} shows how this is done; it also shows that
@c normal quitting is permitted after the first character of input.
$B!J(B@code{read-quoted-char}$B$J$I$N!K$"$k<o$N4X?t$G$O!"(B
@kbd{C-g}$B$OFCJL$K=hM}$5$lCfCG$r0z$-5/$3$7$^$;$s!#(B
@code{inhibit-quit}$B$K(B@code{t}$B$rB+G{$7$FF~NO$rFI$_<h$j!"(B
@code{inhibit-quit}$B$,:FEY(B@code{nil}$B$K$J$k$^$($K(B
@code{quit-flag}$B$r(B@code{nil}$B$K$9$k$3$H$G$=$N$h$&$K$7$^$9!#(B
$B$3$l$r(B@code{read-quoted-char}$B$NDj5A$N0J2<$NH4?h$G<($7$^$7$g$&!#(B
$B:G=i$NF~NOJ8;z$N$"$H$GDL>o$NCfCG$r5v$9J}K!$b<($7$F$$$^$9!#(B

@example
(defun read-quoted-char (&optional prompt)
  "@dots{}@var{documentation}@dots{}"
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            @dots{})
	(and prompt (message "%s-" prompt))
	(setq char (read-event))
	(if inhibit-quit (setq quit-flag nil)))
@c       @r{@dots{}set the variable @code{code}@dots{}})
      @r{@dots{}$BJQ?t(B@code{code}$B$K@_Dj$9$k(B@dots{}})
    code))
@end example

@defvar quit-flag
@c If this variable is non-@code{nil}, then Emacs quits immediately, unless
@c @code{inhibit-quit} is non-@code{nil}.  Typing @kbd{C-g} ordinarily sets
@c @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
@code{inhibit-quit}$B$,(B@code{nil}$B$G$"$l$P!"(B
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H(BEmacs$B$O$?$@$A$KCfCG$9$k!#(B
@kbd{C-g}$B$O!"(B@code{inhibit-quit}$B$K4X$o$i$:!"(B
$BDL>o!"(B@code{quit-flag}$B$K(B@code{nil}$B0J30$r@_Dj$9$k!#(B
@end defvar

@defvar inhibit-quit
@c This variable determines whether Emacs should quit when @code{quit-flag}
@c is set to a value other than @code{nil}.  If @code{inhibit-quit} is
@c non-@code{nil}, then @code{quit-flag} has no special effect.
$B$3$NJQ?t$O!"(B@code{quit-flag}$B$,(B@code{nil}$B0J30$NCM$K@_Dj$5$l$?$H$-$K(B
Emacs$B$,CfCG$9$Y$-$+$I$&$+$r7hDj$9$k!#(B
@code{inhibit-quit}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{quit-flag}$B$KFCJL$J0UL#$O$J$$!#(B
@end defvar

@c @deffn Command keyboard-quit
@deffn $B%3%^%s%I(B keyboard-quit
@c This function signals the @code{quit} condition with @code{(signal 'quit
@c nil)}.  This is the same thing that quitting does.  (See @code{signal}
@c in @ref{Errors}.)
$B$3$N4X?t$O(B@code{(signal 'quit nil)}$B$G(B@code{quit}$B>r7o$rDLCN$9$k!#(B
$B$3$l$OCfCG$HF1$8$3$H$r9T$&!#(B
$B!J(B@ref{Errors}$B$N(B@code{signal}$B$r;2>H!#!K(B
@end deffn

@c   You can specify a character other than @kbd{C-g} to use for quitting.
@c See the function @code{set-input-mode} in @ref{Terminal Input}.
$BCfCG$H$7$F;H$&(B@kbd{C-g}$B0J30$NFC<lJ8;z$r;H$($^$9!#(B
@ref{Terminal Input}$B$N4X?t(B@code{set-input-mode}$B$r;2>H$7$F$/$@$5$$!#(B
 
@node Prefix Command Arguments
@c @section Prefix Command Arguments
@section $BA0CV%3%^%s%I0z?t(B
@c @cindex prefix argument
@c @cindex raw prefix argument
@c @cindex numeric prefix argument
@cindex $BA0CV0z?t(B
@cindex $B@8$NA0CV0z?t(B
@cindex $B?tCMA0CV0z?t(B

@c   Most Emacs commands can use a @dfn{prefix argument}, a number
@c specified before the command itself.  (Don't confuse prefix arguments
@c with prefix keys.)  The prefix argument is at all times represented by a
@c value, which may be @code{nil}, meaning there is currently no prefix
@c argument.  Each command may use the prefix argument or ignore it.
Emacs$B$N$[$H$s$I$N%3%^%s%I$O!"(B@dfn{$BA0CV0z?t(B}$B!J(Bprefix argument$B!K!"(B
$B$D$^$j%3%^%s%I<+?H$N$^$($K;XDj$5$l$??t$rMxMQ$G$-$^$9!#(B
$B!JA0CV0z?t$H%W%l%U%#%C%/%9%-!<$r:.F1$7$J$$$3$H!#!K(B
$BA0CV0z?t$O$D$M$KCM$GI=8=$5$l!"(B
@code{nil}$B$G$"$k$H8=:_$OA0CV0z?t$,$J$$$3$H$rI=$7$^$9!#(B
$B3F%3%^%s%I$O!"A0CV0z?t$r;H$C$F$b$h$$$7!"L5;k$7$F$b$+$^$$$^$;$s!#(B

@c   There are two representations of the prefix argument: @dfn{raw} and
@c @dfn{numeric}.  The editor command loop uses the raw representation
@c internally, and so do the Lisp variables that store the information, but
@c commands can request either representation.
$BA0CV0z?t$K$O(B2$B$D$NI=8=J}K!$,$"$j$^$9!#(B
@dfn{$B@8(B}$B!J(Braw$B!K$H(B@dfn{$B?tCM(B}$B!J(Bnumeric$B!K$G$9!#(B
$B%(%G%#%?%3%^%s%I%k!<%W$G$O!"FbItE*$K$O@8$NI=8=$r;H$$!"(B
$B$=$N>pJs$rJ];}$9$k(BLisp$BJQ?t$b$=$N$h$&$K$7$^$9$,!"(B
$B%3%^%s%I$G$O$I$A$i$NI=8=$rMW5a$7$F$b$+$^$$$^$;$s!#(B

@c   Here are the possible values of a raw prefix argument:
$B@8$NA0CV0z?t$NCM$K$O$D$.$N2DG=@-$,$"$j$^$9!#(B

@itemize @bullet
@item
@c @code{nil}, meaning there is no prefix argument.  Its numeric value is
@c 1, but numerous commands make a distinction between @code{nil} and the
@c integer 1.
$BA0CV0z?t$,$J$$$3$H$r0UL#$9$k(B@code{nil}$B!#(B
$B$=$N?tCM$H$7$F$NCM$O(B1$B$G$"$k$,!"(B
$BB?$/$N%3%^%s%I$G$O(B@code{nil}$B$H@0?t(B1$B$r6hJL$9$k!#(B

@item
@c An integer, which stands for itself.
$B$=$l<+?H$,I=$9@0?t!#(B

@item
@c A list of one element, which is an integer.  This form of prefix
@c argument results from one or a succession of @kbd{C-u}'s with no
@c digits.  The numeric value is the integer in the list, but some
@c commands make a distinction between such a list and an integer alone.
$B@0?t$rMWAG$H$9$k(B1$BMWAG$N%j%9%H!#(B
$B$3$N7A<0$NA0CV0z?t$O!"?t;zJ8;z$J$7$N(B1$B8D0J>e$N(B@kbd{C-u}$B$N7k2L$G$"$k!#(B
$B%j%9%HFb$N?tCM$O@0?t$G$"$k$,!"$=$N$h$&$J%j%9%H$H@0?t$N$_$r6hJL$9$k(B
$B%3%^%s%I$b$"$k!#(B

@item
@c The symbol @code{-}.  This indicates that @kbd{M--} or @kbd{C-u -} was
@c typed, without following digits.  The equivalent numeric value is
@c @minus{}1, but some commands make a distinction between the integer
@c @minus{}1 and the symbol @code{-}.
$B%7%s%\%k(B@code{-}$B!#(B
$B?t;zJ8;z$J$7$K(B@kbd{M--}$B$d(B@kbd{C-u -}$B$rBG$C$?$3$H$rI=$9!#(B
$B$3$l$KEy2A$J?tCM$O(B@minus{}1$B$G$"$k$,!"(B
$B@0?t(B@minus{}1$B$H%7%s%\%k(B@code{-}$B$r6hJL$9$k%3%^%s%I$b$"$k!#(B
@end itemize

@c We illustrate these possibilities by calling the following function with
@c various prefixes:
$B$$$m$$$m$JA0CV0z?t$G$D$.$N4X?t$r8F$S=P$9Nc$r<($7$^$9!#(B

@example
@group
(defun display-prefix (arg)
  "Display the value of the raw prefix arg."
  (interactive "P")
  (message "%s" arg))
@end group
@end example

@noindent
@c Here are the results of calling @code{display-prefix} with various
@c raw prefix arguments:
$B0J2<$O!"@8$NA0CV0z?t$G(B@code{display-prefix}$B$r8F$S=P$7$?7k2L$G$9!#(B

@example
        M-x display-prefix  @print{} nil

C-u     M-x display-prefix  @print{} (4)

C-u C-u M-x display-prefix  @print{} (16)

C-u 3   M-x display-prefix  @print{} 3

@c M-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}
M-3     M-x display-prefix  @print{} 3      ; @r{$B!J(B@code{C-u 3}$B$HF1$8!K(B}

C-u -   M-x display-prefix  @print{} -      

@c M--     M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}
M--     M-x display-prefix  @print{} -      ; @r{$B!J(B@code{C-u -}$B$HF1$8!K(B}

C-u - 7 M-x display-prefix  @print{} -7     

@c M-- 7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}
M-- 7   M-x display-prefix  @print{} -7     ; @r{$B!J(B@code{C-u -7}$B$HF1$8!K(B}
@end example

@c   Emacs uses two variables to store the prefix argument:
@c @code{prefix-arg} and @code{current-prefix-arg}.  Commands such as
@c @code{universal-argument} that set up prefix arguments for other
@c commands store them in @code{prefix-arg}.  In contrast,
@c @code{current-prefix-arg} conveys the prefix argument to the current
@c command, so setting it has no effect on the prefix arguments for future
@c commands.
Emacs$B$O!"A0CV0z?t$rJ];}$9$k$?$a$K(B2$B$D$NJQ?t!"(B
@code{prefix-arg}$B$H(B@code{current-prefix-arg}$B$r;H$$$^$9!#(B
$BB>$N%3%^%s%I8~$1$KA0CV0z?t$r@_Dj$9$k(B@code{universal-argument}$B$J$I$N(B
$B%3%^%s%I$O!"A0CV0z?t$r(B@code{prefix-arg}$B$KJ];}$7$^$9!#(B
$BBP>HE*$K!"(B@code{current-prefix-arg}$B$K$O(B
$B8=:_$N%3%^%s%I$KBP$7$FA0CV0z?t$r1?$VLr3d$,$"$j!"(B
$B$3$NJQ?t$K@_Dj$7$F$b0J8e$N%3%^%s%I$KBP$9$kA0CV0z?t$K$O(B
$B$J$s$N8z2L$b$"$j$^$;$s!#(B

@c   Normally, commands specify which representation to use for the prefix
@c argument, either numeric or raw, in the @code{interactive} declaration.
@c (@xref{Using Interactive}.)  Alternatively, functions may look at the
@c value of the prefix argument directly in the variable
@c @code{current-prefix-arg}, but this is less clean.
$BDL>o!"%3%^%s%I$O!"(B@code{interactive}$B@k8@$K$h$j!"(B
$B!V@8!W$+!V?tCM!W$N$$$:$l$NI=8=$NA0CV0z?t$r;H$&$+;XDj$7$^$9!#(B
$B!J(B@xref{Using Interactive}$B!#!K(B
$B$"$k$$$O!"JQ?t(B@code{current-prefix-arg}$B$K$"$kA0CV0z?t$NCM$r(B
$B4X?t$+$iD>@\8+$F$b$+$^$$$^$;$s$,!"(B
$B$3$l$O8+DL$7$N$h$$J}K!$G$O$"$j$^$;$s!#(B

@defun prefix-numeric-value arg
@c This function returns the numeric meaning of a valid raw prefix argument
@c value, @var{arg}.  The argument may be a symbol, a number, or a list.
@c If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
@c value @minus{}1 is returned; if it is a number, that number is returned;
@c if it is a list, the @sc{car} of that list (which should be a number) is
@c returned.
$B$3$N4X?t$O!"M-8z$J@8$NA0CV0z?t$NCM(B@var{arg}$B$+$i$=$l$KEy2A$J?tCM$rJV$9!#(B
$B0z?t$O!"%7%s%\%k!"?t!"%j%9%H$N$$$:$l$+$G$"$k!#(B
$B$=$l$,(B@code{nil}$B$G$"$k$H!"La$jCM$O(B1$B$G$"$k!#(B
@code{-}$B$G$"$k$H!"La$jCM$O(B@minus{}1$B$G$"$k!#(B
$B?t$G$"$k$H!"$=$N?t$rJV$9!#(B
$B%j%9%H$G$"$k$H!"%j%9%H$N!J?t$G$"$k$O$:$N!K(B@sc{car}$B$rJV$9!#(B
@end defun

@defvar current-prefix-arg
@c This variable holds the raw prefix argument for the @emph{current}
@c command.  Commands may examine it directly, but the usual method for
@c accessing it is with @code{(interactive "P")}.
$B$3$NJQ?t$O!"(B@emph{$B8=:_$N(B}$B%3%^%s%I$KBP$9$k@8$NA0CV0z?t$rJ];}$9$k!#(B
$B%3%^%s%I$,D>@\$3$NJQ?t$rD4$Y$F$b$h$$$,!"(B
$BA0CV0z?t$r;2>H$9$kIaDL$NJ}K!$O(B@code{(interactive "P")}$B$r;H$&$3$H$G$"$k!#(B
@end defvar

@defvar prefix-arg
@c The value of this variable is the raw prefix argument for the
@c @emph{next} editing command.  Commands such as @code{universal-argument}
@c that specify prefix arguments for the following command work by setting
@c this variable.
$B$3$NJQ?t$NCM$O!"(B@emph{$B$D$.$N(B}$BJT=8%3%^%s%I8~$1$N@8$NA0CV0z?t$G$"$k!#(B
$B8eB3$N%3%^%s%I8~$1$NA0CV0z?t$r;XDj$9$k(B@code{universal-argument}$B$J$I$N(B
$B%3%^%s%I$O!"$3$NJQ?t$K@_Dj$9$k$3$H$GF0:n$9$k!#(B
@end defvar

@tindex last-prefix-arg
@defvar last-prefix-arg
@c The raw prefix argument value used by the previous command.
$B$^$($N%3%^%s%I$G;H$o$l$?@8$NA0CV0z?t$NCM!#(B
@end defvar

@c   The following commands exist to set up prefix arguments for the
@c following command.  Do not call them for any other reason.
$B$D$.$N%3%^%s%I$O!"8eB3$N%3%^%s%I8~$1$NA0CV0z?t$r@_Dj$9$k$?$a$N$b$N$G$9!#(B
$B$=$l0J30$NL\E*$K$O8F$P$J$$$G$/$@$5$$!#(B

@c @deffn Command universal-argument
@deffn $B%3%^%s%I(B universal-argument
@c This command reads input and specifies a prefix argument for the
@c following command.  Don't call this command yourself unless you know
@c what you are doing.
$B$3$N%3%^%s%I$OF~NO$rFI$_<h$j!"8eB3$N%3%^%s%I8~$1$NA0CV0z?t$r;XDj$9$k!#(B
$B$J$K$r$7$F$$$k$+M}2r$7$F$$$J$$8B$j!"FI<T<+?H$G$3$N%3%^%s%I$r8F$P$J$$$3$H!#(B
@end deffn

@c @deffn Command digit-argument arg
@deffn $B%3%^%s%I(B digit-argument arg
@c This command adds to the prefix argument for the following command.  The
@c argument @var{arg} is the raw prefix argument as it was before this
@c command; it is used to compute the updated prefix argument.  Don't call
@c this command yourself unless you know what you are doing.
$B$3$N%3%^%s%I$O!"8eB3$N%3%^%s%I8~$1$NA0CV0z?t$KDI2C$9$k!#(B
$B0z?t(B@var{arg}$B$O!"$3$N%3%^%s%I$,8F$S=P$5$l$k$^$($N@8$NA0CV0z?t$G$"$j!"(B
$BA0CV0z?t$r99?7$9$k7W;;$K;H$o$l$k!#(B
$B$J$K$r$7$F$$$k$+M}2r$7$F$$$J$$8B$j!"FI<T<+?H$G$3$N%3%^%s%I$r8F$P$J$$$3$H!#(B
@end deffn

@c @deffn Command negative-argument arg
@deffn $B%3%^%s%I(B negative-argument arg
@c This command adds to the numeric argument for the next command.  The
@c argument @var{arg} is the raw prefix argument as it was before this
@c command; its value is negated to form the new prefix argument.  Don't
@c call this command yourself unless you know what you are doing.
$B$3$N%3%^%s%I$O!"8eB3$N%3%^%s%I8~$1$N?tCMA0CV0z?t$KDI2C$9$k!#(B
$B0z?t(B@var{arg}$B$O!"$3$N%3%^%s%I$,8F$S=P$5$l$k$^$($N@8$NA0CV0z?t$G$"$j!"(B
$B$=$NCM$NId9f$rJQ$($F?7$?$JA0CV0z?t$H$9$k!#(B
$B$J$K$r$7$F$$$k$+M}2r$7$F$$$J$$8B$j!"FI<T<+?H$G$3$N%3%^%s%I$r8F$P$J$$$3$H!#(B
@end deffn

@node Recursive Editing
@c @section Recursive Editing
@section $B:F5"JT=8(B
@c @cindex recursive command loop
@c @cindex recursive editing level
@c @cindex command loop, recursive
@cindex $B:F5"%3%^%s%I%k!<%W(B
@cindex $B:F5"JT=8%l%Y%k(B
@cindex $B%3%^%s%I%k!<%W!":F5"(B

@c   The Emacs command loop is entered automatically when Emacs starts up.
@c This top-level invocation of the command loop never exits; it keeps
@c running as long as Emacs does.  Lisp programs can also invoke the
@c command loop.  Since this makes more than one activation of the command
@c loop, we call it @dfn{recursive editing}.  A recursive editing level has
@c the effect of suspending whatever command invoked it and permitting the
@c user to do arbitrary editing before resuming that command.
Emacs$B$,F0:n$r;O$a$k$H!"(BEmacs$B$N%3%^%s%I%k!<%W$K<+F0E*$KF~$j$^$9!#(B
$B$3$N%H%C%W%l%Y%k$N%3%^%s%I%k!<%W$+$i$O$1$C$7$FH4$1$k$3$H$O$J$/!"(B
Emacs$B$,F0$$$F$$$k8B$jF0:n$7B3$1$^$9!#(B
Lisp$B%W%m%0%i%`$+$i%3%^%s%I%k!<%W$r5/F0$9$k$3$H$b$G$-$^$9!#(B
$B$=$&$9$k$H!"3h@-$J%3%^%s%I%k!<%W$,J#?t:n$i$l$k$3$H$K$J$k$N$G!"(B
$B$=$l$r(B@dfn{$B:F5"JT=8(B}$B!J(Brecursive editing$B!K$H8F$S$^$9!#(B
$B:F5"JT=8%l%Y%k$K$O!"$=$l$r5/F0$7$?%3%^%s%I$r0l;~5Y;_$5$;!"(B
$BEv3:%3%^%s%I$r:F3+$9$k$^$G%f!<%6!<$K$I$s$JJT=8$G$b5v$98z2L$,$"$j$^$9!#(B

@c   The commands available during recursive editing are the same ones
@c available in the top-level editing loop and defined in the keymaps.
@c Only a few special commands exit the recursive editing level; the others
@c return to the recursive editing level when they finish.  (The special
@c commands for exiting are always available, but they do nothing when
@c recursive editing is not in progress.)
$B:F5"JT=8Cf$KMxMQ2DG=$J%3%^%s%I$O!"%H%C%W%l%Y%k$N%3%^%s%I%k!<%W$H(B
$BF1$8$b$N$G$"$j%-!<%^%C%W$GDj5A$5$l$^$9!#(B
$B:F5"JT=8$rH4$1$k$?$a$N?t8D$NFCJL$J%3%^%s%I$,$"$j!"(B
$B40N;$9$k$H:F5"JT=8%l%Y%k$+$iH4$1$kJL$N%3%^%s%I$b$"$j$^$9!#(B
$B!J:F5"JT=8$rH4$1$k%3%^%s%I$O$D$M$KMxMQ2DG=$G$"$k$,!"(B
$B:F5"JT=8Cf$G$J$$$H$J$K$b9T$o$J$$!#!K(B

@c   All command loops, including recursive ones, set up all-purpose error
@c handlers so that an error in a command run from the command loop will
@c not exit the loop.
$B:F5"JT=8$r4^$`$9$Y$F$N%3%^%s%I%k!<%W$G$O!"(B
$B%3%^%s%I%k!<%W$+$i<B9T$7$?%3%^%s%I$N%(%i!<$K$h$C$F(B
$B%3%^%s%I%k!<%W$+$iH4$1=P$5$J$$$h$&$KHFMQL\E*$N%(%i!<%O%s%I%i$r@_Dj$7$^$9!#(B

@c @cindex minibuffer input
@cindex $B%_%K%P%C%U%!F~NO(B
@c   Minibuffer input is a special kind of recursive editing.  It has a few
@c special wrinkles, such as enabling display of the minibuffer and the
@c minibuffer window, but fewer than you might suppose.  Certain keys
@c behave differently in the minibuffer, but that is only because of the
@c minibuffer's local map; if you switch windows, you get the usual Emacs
@c commands.
$B%_%K%P%C%U%!$G$NF~NO$O!"FCJL$J<oN`$N:F5"JT=8$G$9!#(B
$B$3$l$K$O!"%_%K%P%C%U%!$d%_%K%P%C%U%!MQ%&%#%s%I%&$rI=<($9$k$J$I$NFCJL$J(B
$B=hM}$,$"$j$^$9$,!"FI<T$,9M$($k$h$j$O>/$J$$$N$G$9!#(B
$B%_%K%P%C%U%!$G$OFCJL$J$U$k$^$$$r$9$k%-!<$b$"$j$^$9$,!"(B
$B$=$l$i$O%_%K%P%C%U%!$N%m!<%+%k%^%C%W$K$h$k$b$N$G$9!#(B
$B%&%#%s%I%&$r@Z$jBX$($k$H!"(BEmacs$B$NIaDL$N%3%^%s%I$r;H$($^$9!#(B

@c @cindex @code{throw} example
@cindex @code{throw}$B$NNc(B
@cindex $BNc!"(B@code{throw}
@kindex exit
@c @cindex exit recursive editing
@c @cindex aborting
@cindex $B:F5"JT=8$N=*N;(B
@cindex $B6/@)=*N;(B
@c   To invoke a recursive editing level, call the function
@c @code{recursive-edit}.  This function contains the command loop; it also
@c contains a call to @code{catch} with tag @code{exit}, which makes it
@c possible to exit the recursive editing level by throwing to @code{exit}
@c (@pxref{Catch and Throw}).  If you throw a value other than @code{t},
@c then @code{recursive-edit} returns normally to the function that called
@c it.  The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
@c Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
@c control returns to the command loop one level up.  This is called
@c @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
$B:F5"JT=8%l%Y%k$r5/F0$9$k$K$O!"4X?t(B@code{recursive-edit}$B$r8F$S=P$7$^$9!#(B
$B$3$N4X?t$K$O%3%^%s%I%k!<%W$,4^$^$l$F$$$^$9!#(B
$B$5$i$K!"(B@code{exit}$B$rH<$C$?(B@code{catch}$B$N8F$S=P$7$b$"$j!"(B
$B$3$l$K$h$j!"(B@code{exit}$B$XEj$2$k$3$H$G(B
$B:F5"JT=8%l%Y%k$+$iH4$1=P$;$k$h$&$K$J$C$F$$$^$9(B
$B!J(B@pxref{Catch and Throw}$B!K!#(B
@code{t}$B0J30$NCM$rEj$2$k$H!"(B@code{recursive-edit}$B$O!"(B
$B8F$S=P$7B&$N4X?t$XIaDL$KLa$j$^$9!#(B
$B%3%^%s%I(B@kbd{C-M-c}$B!J(B@code{exit-recursive-edit}$B!K$O!"$3$l$r9T$$$^$9!#(B
$BCM(B@code{t}$B$rEj$2$k$H(B@code{recursive-edit}$B$KCfCG$r0z$-5/$3$7!"(B
1$B$D>e$N%l%Y%k$N%3%^%s%I%k!<%W$X@)8f$rLa$7$^$9!#(B
$B$3$l$r(B@dfn{$B6/@)=*N;(B}$B!J(Baborting$B!K$H8F$S!"(B
@kbd{C-]}$B!J(B@code{abort-recursive-edit}$B!K$G9T$($^$9!#(B

@c   Most applications should not use recursive editing, except as part of
@c using the minibuffer.  Usually it is more convenient for the user if you
@c change the major mode of the current buffer temporarily to a special
@c major mode, which should have a command to go back to the previous mode.
@c (The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to
@c give the user different text to edit ``recursively'', create and select
@c a new buffer in a special mode.  In this mode, define a command to
@c complete the processing and go back to the previous buffer.  (The
@c @kbd{m} command in Rmail does this.)
$B%_%K%P%C%U%!$r;H$&>l9g$r=|$$$F!"$[$H$s$I$N%"%W%j%1!<%7%g%s$G$O(B
$B:F5"JT=8$r;H$&$Y$-$G$O$"$j$^$;$s!#(B
$B%+%l%s%H%P%C%U%!$N%a%8%c!<%b!<%I$r(B
$B0l;~E*$JFCJL$J%a%8%c!<%b!<%I$KJQ99$9$k$[$&$,!"(B
$B0lHL$K$O%f!<%6!<$K$H$C$F$h$jJXMx$G$9!#(B
$B$?$@$7!"Ev3:%a%8%c!<%b!<%I$K$O!"(B
$B$^$($N%b!<%I$KLa$k%3%^%s%I$rMQ0U$7$F$*$-$^$9!#(B
$B!J(Brmail$B$N%3%^%s%I(B@kbd{e}$B$O!"$3$NJ}<0$r;H$C$F$$$k!#!K(B
$B$"$k$$$O!"!X:F5"E*$K!YJT=8$9$kJL$N%F%-%9%H$r%f!<%6!<$KM?$($?$$>l9g$K$O!"(B
$BFCJL$J%b!<%I$N?7$?$J%P%C%U%!$r:n@.$7$F$=$l$rA*Br$7$^$9!#(B
$BEv3:%b!<%I$K$O!"=hM}$r=*$($F$^$($N%P%C%U%!$KLa$k%3%^%s%I$r(B
$BDj5A$7$F$*$-$^$9!#(B
$B!J(Brmail$B$N%3%^%s%I(B@kbd{m}$B$O!"$3$N$h$&$K$9$k!#!K(B

@c   Recursive edits are useful in debugging.  You can insert a call to
@c @code{debug} into a function definition as a sort of breakpoint, so that
@c you can look around when the function gets there.  @code{debug} invokes
@c a recursive edit but also provides the other features of the debugger.
$B:F5"JT=8$O%G%P%C%0$KJXMx$G$9!#(B
$B%V%l!<%/%]%$%s%H$N0l<o$H$7$F4X?tDj5A$K(B
@code{debug}$B$N8F$S=P$7$rA^F~$7$F$*$/$H!"(B
$B$=$N2U=j$KC#$7$?$H$-$K$$$m$$$m$HD4$Y$i$l$^$9!#(B
@code{debug}$B$O:F5"JT=8$r5/F0$7$^$9$,!"%G%P%C%,$H$7$F$N5!G=$bDs6!$7$^$9!#(B

@c   Recursive editing levels are also used when you type @kbd{C-r} in
@c @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
@code{query-replace}$B$G(B@kbd{C-r}$B$rBG$C$?$j!"(B
@kbd{C-x q}$B!J(B@code{kbd-macro-query}$B!K$r;H$C$?$H$-$K$b(B
$B:F5"JT=8%l%Y%k$,;H$o$l$^$9!#(B

@defun recursive-edit
@c @cindex suspend evaluation
@cindex $BI>2A$N0l;~5Y;_(B
@c This function invokes the editor command loop.  It is called
@c automatically by the initialization of Emacs, to let the user begin
@c editing.  When called from a Lisp program, it enters a recursive editing
@c level.
$B$3$N4X?t$O%(%G%#%?%3%^%s%I%k!<%W$r5/F0$9$k!#(B
Emacs$B$N=i4|2=2aDx$G<+F0E*$K8F$S=P$5$l!"%f!<%6!<$,JT=8$G$-$k$h$&$K$9$k!#(B
Lisp$B%W%m%0%i%`$+$i8F$P$l$k$H!":F5"JT=8%l%Y%k$KF~$k!#(B

@c   In the following example, the function @code{simple-rec} first
@c advances point one word, then enters a recursive edit, printing out a
@c message in the echo area.  The user can then do any editing desired, and
@c then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
$B0J2<$NNc$G$O!"4X?t(B@code{simple-rec}$B$O!"$^$:(B1$BC18lJ,%]%$%s%H$r?J$a!"(B
$B%(%3!<NN0h$K%a%C%;!<%8$rI=<($7$F:F5"JT=8$KF~$k!#(B
$B$=$&$9$k$H!"%f!<%6!<$OK>$`$3$H$O$J$s$G$b$G$-$k$h$&$K$J$j!"(B
$B!J:F5"JT=8$r!KH4$1$k$?$a$K(B@kbd{C-M-c}$B$rBG$D$H!"(B
@code{simple-rec}$B$N<B9T$r7QB3$9$k!#(B

@example
(defun simple-rec ()
  (forward-word 1)
  (message "Recursive edit in progress")
  (recursive-edit)
  (forward-word 1))
     @result{} simple-rec
(simple-rec)
     @result{} nil
@end example
@end defun

@c @deffn Command exit-recursive-edit
@deffn $B%3%^%s%I(B exit-recursive-edit
@c This function exits from the innermost recursive edit (including
@c minibuffer input).  Its definition is effectively @code{(throw 'exit
@c nil)}.  
$B$3$N4X?t$O!"!J%_%K%P%C%U%!$G$NF~NO$r4^$`!K$b$C$H$bFbB&$N:F5"JT=8$+$iH4$1$k!#(B
$B$=$N4X?tDj5A$O<B<AE*$K$O(B@code{(throw 'exit nil)}$B$G$"$k!#(B
@end deffn

@c @deffn Command abort-recursive-edit
@deffn $B%3%^%s%I(B abort-recursive-edit
@c This function aborts the command that requested the innermost recursive
@c edit (including minibuffer input), by signaling @code{quit} 
@c after exiting the recursive edit.  Its definition is effectively
@c @code{(throw 'exit t)}.  @xref{Quitting}.
$B$3$N4X?t$O!":F5"JT=8$+$iH4$1$?$"$H$G(B@code{quit}$B$rDLCN$9$k$3$H$G!"(B
$B!J%_%K%P%C%U%!$G$NF~NO$r4^$`!K$b$C$H$bFbB&$N:F5"JT=8$r(B
$BMW@A$7$?%3%^%s%I$r6/@)=*N;$9$k!#(B
$B$=$N4X?tDj5A$O<B<AE*$K$O(B@code{(throw 'exit t)}$B$G$"$k!#(B
@pxref{Quitting}$B!#(B
@end deffn

@c @deffn Command top-level
@deffn $B%3%^%s%I(B top-level
@c This function exits all recursive editing levels; it does not return a
@c value, as it jumps completely out of any computation directly back to
@c the main command loop.
$B$3$N4X?t$O!"$9$Y$F$N:F5"JT=8$rH4$1$k!#(B
$B$9$Y$F$N7W;;$rH4$1=P$F%a%$%s$N%3%^%s%I%k!<%W$XD>@\La$k$?$a!"CM$OJV$5$J$$!#(B
@end deffn

@defun recursion-depth
@c This function returns the current depth of recursive edits.  When no
@c recursive edit is active, it returns 0.
$B$3$N4X?t$O:F5"JT=8$N8=:_$N?<$5$rJV$9!#(B
$B3h@-$J:F5"JT=8$,$J$1$l$P(B0$B$rJV$9!#(B
@end defun

@node Disabling Commands
@c @section Disabling Commands
@section $B%3%^%s%I$r6X;_$9$k(B
@c @cindex disabled command
@cindex $B6X;_%3%^%s%I(B

@c   @dfn{Disabling a command} marks the command as requiring user
@c confirmation before it can be executed.  Disabling is used for commands
@c which might be confusing to beginning users, to prevent them from using
@c the commands by accident.
@dfn{$B%3%^%s%I$r6X;_$9$k(B}$B$H$O!"(B
$B%3%^%s%I$r<B9T$9$k$^$($K%f!<%6!<$N3NG'$rI,MW$H$9$k$h$&$K(B
$B%3%^%s%I$K0u$rIU$1$k$3$H$G$9!#(B
$B%3%^%s%I$r6X;_$9$k$N$O!"(B
$B=i?4<T$K:.Mp$r$b$?$i$92DG=@-$N$"$k%3%^%s%I$KBP$7$F$d!"(B
$B%3%^%s%I$N8mMQ$rKI$0$?$a$G$9!#(B

@kindex disabled
@c   The low-level mechanism for disabling a command is to put a
@c non-@code{nil} @code{disabled} property on the Lisp symbol for the
@c command.  These properties are normally set up by the user's
@c @file{.emacs} file with Lisp expressions such as this:
$B%3%^%s%I$r6X;_$9$kDc%l%Y%k$N5!9=$O!"(B
$B%3%^%s%I$N(BLisp$B%7%s%\%k$K(B@code{nil}$B0J30$NB0@-(B@code{disabled}$B$rF~$l$k$3$H$G$9!#(B
$B$3$l$i$NB0@-$O!"DL>o!"%f!<%6!<$N(B@file{.emacs}$B%U%!%$%k$K$F(B
$B$D$.$N$h$&$J(BLisp$B<0$G@_Dj$7$^$9!#(B

@example
(put 'upcase-region 'disabled t)
@end example

@noindent
@c For a few commands, these properties are present by default and may be
@c removed by the @file{.emacs} file.
$B?t8D$N%3%^%s%I$K$O%G%U%)%k%H$G$3$l$i$NB0@-$,$"$j$^$9$+$i!"(B
@file{.emacs}$B%U%!%$%k$GB0@-$r<h$j=|$-$^$9!#(B

@c   If the value of the @code{disabled} property is a string, the message
@c saying the command is disabled includes that string.  For example:
$BB0@-(B@code{disabled}$B$NCM$OJ8;zNs$G$"$j!"(B
$B%3%^%s%I$r6X;_$7$?$3$H$rI=$9%a%C%;!<%8$G$9!#(B
$B$?$H$($P$D$.$N$H$*$j$G$9!#(B

@example
(put 'delete-region 'disabled
     "Text deleted this way cannot be yanked back!\n")
@end example

@c   @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
@c what happens when a disabled command is invoked interactively.
@c Disabling a command has no effect on calling it as a function from Lisp
@c programs.
$B6X;_$7$?%3%^%s%I$rBPOCE*$K5/F0$9$k$H$I$&$J$k$+$K$D$$$F(B
$B>\$7$/$O(B@xref{Disabling,, $B;HMQ6X;_%3%^%s%I(B, emacs, GNU Emacs $B%^%K%e%"%k(B}$B!#(B
$B%3%^%s%I$r6X;_$7$F$b!"(BLisp$B%W%m%0%i%`$+$i4X?t$H$7$F8F$S=P$9$3$H$K$O(B
$B$J$s$N1F6A$b$"$j$^$;$s!#(B

@c @deffn Command enable-command command
@deffn $B%3%^%s%I(B enable-command command
@c Allow @var{command} to be executed without special confirmation from now
@c on, and (if the user confirms) alter the user's @file{.emacs} file so
@c that this will apply to future sessions.
$B$3$l0J9_!"FCJL$J3NG'$J$7$K(B@var{command}$B$r<B9T2DG=$K$9$k!#(B
$B$5$i$K!J%f!<%6!<$,N;>5$9$l$P!K%f!<%6!<$N(B@file{.emacs}$B%U%!%$%k$rJQ99$7$F!"(B
$B>-Mh$N%;%C%7%g%s$G$b$=$N$h$&$K$9$k!#(B
@end deffn

@c @deffn Command disable-command command
@deffn $B%3%^%s%I(B disable-command command
@c Require special confirmation to execute @var{command} from now on, and
@c (if the user confirms) alter the user's @file{.emacs} file so that this
@c will apply to future sessions.
$B$3$l0J9_!"(B@var{command}$B$N<B9T$K$OFCJL$J3NG'$rI,MW$H$9$k$h$&$K$9$k!#(B
$B$5$i$K!J%f!<%6!<$,N;>5$9$l$P!K%f!<%6!<$N(B@file{.emacs}$B%U%!%$%k$rJQ99$7$F!"(B
$B>-Mh$N%;%C%7%g%s$G$b$=$N$h$&$K$9$k!#(B
@end deffn

@defvar disabled-command-hook
@c When the user invokes a disabled command interactively, this normal hook
@c is run instead of the disabled command.  The hook functions can use
@c @code{this-command-keys} to determine what the user typed to run the
@c command, and thus find the command itself.  @xref{Hooks}.
$B6X;_$7$?%3%^%s%I$r%f!<%6!<$,BPOCE*$K5/F0$7$?$H$-!"(B
$B6X;_$7$?%3%^%s%I$N$+$o$j$K$3$N%N!<%^%k%U%C%/$r<B9T$9$k!#(B
$B%U%C%/4X?t$G$O!"(B@code{this-command-keys}$B$r;H$C$F(B
$B%3%^%s%I$r<B9T$9$k$?$a$K%f!<%6!<$,$J$K$rF~NO$7$?$+$rD4$Y!"(B
$B%3%^%s%I$=$N$b$N$rC5$7=P$;$k!#(B
@pxref{Hooks}$B!#(B

@c By default, @code{disabled-command-hook} contains a function that asks
@c the user whether to proceed.
$B%G%U%)%k%H$G$O!"(B@code{disabled-command-hook}$B$K$O!"(B
$B%f!<%6!<$K=hM}$r?J$a$k$+$I$&$+$rLd$$9g$o$;$k4X?t$,F~$C$F$$$k!#(B
@end defvar

@node Command History
@c @section Command History
@section $B%3%^%s%IMzNr(B
@c @cindex command history
@c @cindex complex command
@c @cindex history of commands
@cindex $B%3%^%s%IMzNr(B
@cindex $BJ#;($J%3%^%s%I(B
@cindex $BMzNr!"%3%^%s%I(B

@c   The command loop keeps a history of the complex commands that have
@c been executed, to make it convenient to repeat these commands.  A
@c @dfn{complex command} is one for which the interactive argument reading
@c uses the minibuffer.  This includes any @kbd{M-x} command, any
@c @kbd{M-:} command, and any command whose @code{interactive}
@c specification reads an argument from the minibuffer.  Explicit use of
@c the minibuffer during the execution of the command itself does not cause
@c the command to be considered complex.
$B%3%^%s%I%k!<%W$G$O!"<B9T$7$?J#;($J%3%^%s%I$NMzNr$r4IM}$7$F$$$F!"(B
$B$=$l$i$N%3%^%s%I$r4JC1$K7+$jJV$;$k$h$&$K$7$F$$$^$9!#(B
@dfn{$BJ#;($J%3%^%s%I(B}$B$H$O!"%_%K%P%C%U%!$r;H$C$F0z?t$rFI$`%3%^%s%I$G$9!#(B
$B$3$l$K$O!"G$0U$N(B@kbd{M-x}$B%3%^%s%I!"G$0U$N(B@kbd{M-:}$B%3%^%s%I!"(B
$B%_%K%P%C%U%!$+$i0z?t$rFI$_<h$k(B@code{interactive}$B;XDj$r;}$DG$0U$N%3%^%s%I$,(B
$B4^$^$l$^$9!#(B
$B%3%^%s%I<+?H$N<B9TCf$KL@<(E*$K%_%K%P%C%U%!$r;H$C$F$b!"(B
$BJ#;($J%3%^%s%I$H$O$_$J$7$^$;$s!#(B

@defvar command-history
@c This variable's value is a list of recent complex commands, each
@c represented as a form to evaluate.  It continues to accumulate all
@c complex commands for the duration of the editing session, but when it
@c reaches the maximum size (specified by the variable
@c @code{history-length}), the oldest elements are deleted as new ones are
@c added.
$B$3$NJQ?t$NCM$O!":G6a;H$C$?J#;($J%3%^%s%I$N%j%9%H$G$"$j!"(B
$B3FMWAG$OI>2A$9$Y$-%U%)!<%`$rI=$9!#(B
$BJT=8%;%C%7%g%sCf$O!"$9$Y$F$NJ#;($J%3%^%s%I$r=8@Q$9$k$,!"(B
$B!JJQ?t(B@code{history-length}$B$G;XDj$5$l$k!K:GBg%5%$%:$KC#$9$k$H(B
$B?7$7$$MWAG$rDI2C$9$k$?$S$K8E$$MWAG$r:o=|$9$k!#(B

@example
@group
command-history
@result{} ((switch-to-buffer "chistory.texi")
    (describe-key "^X^[")
    (visit-tags-table "~/emacs/src/")
    (find-tag "repeat-complex-command"))
@end group
@end example
@end defvar

@c   This history list is actually a special case of minibuffer history
@c (@pxref{Minibuffer History}), with one special twist: the elements are
@c expressions rather than strings.
$B$3$NMzNr%j%9%H$O!"<B:]$K$O%_%K%P%C%U%!MzNr!J(B@pxref{Minibuffer History}$B!K(B
$B$NFCJL$J>l9g$G$9!#(B
$BMWAG$OJ8;zNs$G$O$J$/<0$J$N$G$9!#(B

@c   There are a number of commands devoted to the editing and recall of
@c previous commands.  The commands @code{repeat-complex-command}, and
@c @code{list-command-history} are described in the user manual
@c (@pxref{Repetition,,, emacs, The GNU Emacs Manual}).  Within the
@c minibuffer, the usual minibuffer history commands are available.
$B$^$($N%3%^%s%I$rJT=8$7$?$j<h$j=P$9$?$a$N@lMQ%3%^%s%I$,$?$/$5$s$"$j$^$9!#(B
$B%3%^%s%I(B@code{repeat-complex-command}$B$H(B@code{list-command-history}$B$O!"(B
$B%f!<%6!<%^%K%e%"%k(B
$B!J(B@pxref{Repetition,, $B%_%K%P%C%U%!%3%^%s%I$N7+$jJV$7(B, emacs,
GNU Emacs $B%^%K%e%"%k(B}$B!K$K@bL@$7$F$"$j$^$9!#(B
$B%_%K%P%C%U%!Fb$G$O!"DL>o$N%_%K%P%C%U%!MzNr%3%^%s%I$r;H$($^$9!#(B

@node Keyboard Macros
@c @section Keyboard Macros
@section $B%-!<%\!<%I%^%/%m(B
@c @cindex keyboard macros
@cindex $B%-!<%\!<%I%^%/%m(B

@c   A @dfn{keyboard macro} is a canned sequence of input events that can
@c be considered a command and made the definition of a key.  The Lisp
@c representation of a keyboard macro is a string or vector containing the
@c events.  Don't confuse keyboard macros with Lisp macros
@c (@pxref{Macros}).
@dfn{$B%-!<%\!<%I%^%/%m(B}$B$O!"(B
$B%3%^%s%I$H$_$J$;$kF~NO%$%Y%s%H$N$^$H$^$C$?Ns$G$"$j!"(B
$B%-!<$NDj5A$+$i9=@.$5$l$^$9!#(B
Lisp$B$K$*$1$k%-!<%\!<%I%^%/%m$NI=8=$O!"(B
$B%$%Y%s%H$r4^$s$@J8;zNs$d%Y%/%H%k$G$9!#(B
$B%-!<%\!<%I%^%/%m$H(BLisp$B%^%/%m!J(B@pxref{Macros}$B!K$r:.F1$7$J$$$G$/$@$5$$!#(B

@defun execute-kbd-macro kbdmacro &optional count
@c This function executes @var{kbdmacro} as a sequence of events.  If
@c @var{kbdmacro} is a string or vector, then the events in it are executed
@c exactly as if they had been input by the user.  The sequence is
@c @emph{not} expected to be a single key sequence; normally a keyboard
@c macro definition consists of several key sequences concatenated.
$B$3$N4X?t$O%-!<%\!<%I%^%/%m(B@var{kbdmacro}$B$r%$%Y%s%HNs$H$7$F<B9T$9$k!#(B
@var{kbdmacro}$B$,J8;zNs$+%Y%/%H%k$G$"$k$H!"(B
$B$=$NCf$N%$%Y%s%H$r%f!<%6!<$,F~NO$7$?>l9g$H$^$C$?$/F1MM$K<B9T$9$k!#(B
$BNs$OC10l$N%-!<%$%Y%s%H$G$"$kI,MW$O(B@emph{$B$J$$(B}$B!#(B
$BDL>o!"%-!<%\!<%I%^%/%m$NDj5A$O!"J#?t$N%-!<Ns$rO"7k$7$?$b$N$G$"$k!#(B

@c If @var{kbdmacro} is a symbol, then its function definition is used in
@c place of @var{kbdmacro}.  If that is another symbol, this process repeats.
@c Eventually the result should be a string or vector.  If the result is
@c not a symbol, string, or vector, an error is signaled.
@var{kbdmacro}$B$,%7%s%\%k$G$"$k$H!"(B
@var{kbdmacro}$B$N$+$o$j$K$=$N4X?tDj5A$rMQ$$$k!#(B
$B$=$l$,$5$i$KJL$N%7%s%\%k$G$"$k$H!"$3$N=hM}$r7+$jJV$9!#(B
$B:G=*E*$J7k2L$O!"J8;zNs$+%Y%/%H%k$G$"$k$3$H!#(B
$B7k2L$,%7%s%\%k$G$bJ8;zNs$G$b%Y%/%H%k$G$b$J$$$H!"(B
$B%(%i!<$rDLCN$9$k!#(B

@c The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
@c many times.  If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
@c executed once.  If it is 0, @var{kbdmacro} is executed over and over until it
@c encounters an error or a failing search.  
$B0z?t(B@var{count}$B$O7+$jJV$72s?t$G$"$j!"(B
@var{kbdmacro}$B$r$=$N2s?t$@$1<B9T$9$k!#(B
@var{count}$B$r>JN,$9$k$+(B@code{nil}$B$G$"$k$H!"(B@var{kbdmacro}$B$r(B1$B2s<B9T$9$k!#(B
@var{count}$B$,(B0$B$G$"$k$H!"(B
@var{kbdmacro}$B$N<B9T$r%(%i!<$K=P2q$&$+C5:w$K<:GT$9$k$^$G7+$jJV$9!#(B

@c @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
@code{execute-kbd-macro}$B$r;H$C$?Nc$K$D$$$F$O(B@pxref{Reading One Event}$B!#(B
@end defun

@defvar executing-macro
@c This variable contains the string or vector that defines the keyboard
@c macro that is currently executing.  It is @code{nil} if no macro is
@c currently executing.  A command can test this variable so as to behave
@c differently when run from an executing macro.  Do not set this variable
@c yourself.
$B$3$NJQ?t$O!"8=:_<B9TCf$N%-!<%\!<%I%^%/%m$NDj5A$G$"$k(B
$BJ8;zNs$d%Y%/%H%k$rJ];}$9$k!#(B
$B$3$l$,(B@code{nil}$B$G$"$k$H!"8=:_<B9TCf$N%^%/%m$O$J$$!#(B
$B%3%^%s%I$G$3$NJQ?t$r8!::$9$k$3$H$G!"(B
$B%^%/%m<B9T$G5/F0$5$l$?$H$-$N$U$k$^$$$rJQ99$G$-$k!#(B
$BFI<T<+?H$O$3$NJQ?t$K@_Dj$7$J$$$3$H!#(B
@end defvar

@defvar defining-kbd-macro
@c This variable indicates whether a keyboard macro is being defined.  A
@c command can test this variable so as to behave differently while a macro
@c is being defined.  The commands @code{start-kbd-macro} and
@c @code{end-kbd-macro} set this variable---do not set it yourself.
$B$3$NJQ?t$O!"%-!<%\!<%I%^%/%m$rDj5ACf$+$I$&$+$rI=$9!#(B
$B%3%^%s%I$G$3$NJQ?t$r8!::$9$k$3$H$G!"%^%/%mDj5ACf$N$U$k$^$$$rJQ99$G$-$k!#(B
$B%3%^%s%I(B@code{start-kbd-macro}$B$H(B@code{end-kbd-macro}$B$,$3$NJQ?t$K@_Dj$9$k!#(B
$BFI<T<+?H$O@_Dj$7$J$$$3$H!#(B

@c The variable is always local to the current terminal and cannot be
@c buffer-local.  @xref{Multiple Displays}.
$B$3$NJQ?t$O8=:_$NC<Kv$KBP$7$F$D$M$K%m!<%+%k$G$"$j!"(B
$B%P%C%U%!$KBP$7$F%m!<%+%k$K$O$J$i$J$$!#(B
@pxref{Multiple Displays}$B!#(B
@end defvar

@defvar last-kbd-macro
@c This variable is the definition of the most recently defined keyboard
@c macro.  Its value is a string or vector, or @code{nil}.
$B$3$NJQ?t$O!"$b$C$H$b:G6a$KDj5A$5$l$?%-!<%\!<%I%^%/%m$NDj5A$G$"$k!#(B
$B$=$NCM$O!"J8;zNs$+%Y%/%H%k!"$"$k$$$O!"(B@code{nil}$B$G$"$k!#(B

@c The variable is always local to the current terminal and cannot be
@c buffer-local.  @xref{Multiple Displays}.
$B$3$NJQ?t$O8=:_$NC<Kv$KBP$7$F$D$M$K%m!<%+%k$G$"$j!"(B
$B%P%C%U%!$KBP$7$F%m!<%+%k$K$O$J$i$J$$!#(B
@pxref{Multiple Displays}$B!#(B
@end defvar