@code{last-command} describes the command before that. @xref{Hooks}.
@end defvar
- An erroneous function in the @code{pre-command-hook} list could easily
-make Emacs go into an infinite loop of errors. To protect you from this
-sort of painful problem, Emacs sets the hook variable to @code{nil}
-temporarily while running the functions in the hook. Thus, if a hook
-function gets an error, the hook variable is left as @code{nil}. Emacs
-does the same thing for @code{post-command-hook}.
-
Quitting is suppressed while running @code{pre-command-hook} and
-@code{post-command-hook}; this is because otherwise a quit, happening by
-chance within one of these hooks, would turn off the hook.
-
- One inconvenient result of these protective features is that you
-cannot have a function in @code{post-command-hook} or
-@code{pre-command-hook} which changes the value of that variable. But
-that's not a real limitation. If you want hook functions to change the
-hook, simply add one fixed function to the hook, and code that function
-to look in another hook variable for other functions to call. Here is
-an example:
-
-@example
-;; @r{Set up the mechanism.}
-(defvar current-post-command-function nil)
-(defun run-current-post-command-function ()
- (if current-post-command-function
- (funcall current-post-command-function)))
-(add-hooks 'post-command-hook
- 'run-current-post-command-function)
-
-;; @r{Here's a hook function which replaces itself}
-;; @r{with a different hook function to run next time.}
-(defun first-post-command-function ()
- (setq current-post-command-function
- 'second-post-command-function))
-@end example
+@code{post-command-hook}. If an error happens while executing one of
+these hooks, it terminates execution of the hook, but that is all it
+does.
@node Defining Commands
@section Defining Commands
command.
@cindex argument evaluation form
+If this expression reads keyboard input (this includes using the
+minibuffer), keep in mind that the integer value of point or the mark
+before reading input may be incorrect after reading input. This is
+because the current buffer may be receiving subprocess output;
+if subprocess output arrives while the command is waiting for input,
+it could relocate point and the mark.
+
+Here's an example of what @emph{not} to do:
+
+@smallexample
+(interactive
+ (list (region-beginning) (region-end)
+ (read-string "Foo: " nil 'my-history)))
+@end smallexample
+
+@noindent
+Here's how to avoid the problem, by examining point and the mark only
+after reading the keyboard input:
+
+@smallexample
+(interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+ (list (region-beginning) (region-end) string)))
+@end smallexample
+
@item
@cindex argument prompt
It may be a string; then its contents should consist of a code character
This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.
+@item K
+A key sequence, whose definition you intend to change. This works like
+@samp{k}, except that it suppresses, for the last input event in the key
+sequence, the conversions that are normally used (when necessary) to
+convert an undefined key into a defined one.
+
@item m
@cindex marker argument
The position of the mark, as an integer. No I/O.
@item N
@cindex raw prefix argument usage
-The raw prefix argument. If the prefix argument is @code{nil}, then
-read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
+The numeric prefix argument; but if there is no prefix argument, read a
+number as with @kbd{n}. Requires a number. @xref{Prefix Command
Arguments}. Prompt.
@item p
The interactively callable objects include strings and vectors (treated
as keyboard macros), lambda expressions that contain a top-level call to
-@code{interactive}, compiled function objects made from such lambda
+@code{interactive}, byte-code function objects made from such lambda
expressions, autoload objects that are declared as interactive
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
The value is copied from @code{this-command} when a command returns to
the command loop, except when the command specifies a prefix argument
for the following command.
+
+This variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
@defvar this-command
@cindex kill command repetition
Some commands set this variable during their execution, as a flag for
-whatever command runs next. In particular, the functions that kill text
+whatever command runs next. In particular, the functions for killing text
set @code{this-command} to @code{kill-region} so that any kill commands
immediately following will know to append the killed text to the
previous kill.
@xref{Input Focus}.
@end defvar
-@defvar echo-keystrokes
-This variable determines how much time should elapse before command
-characters echo. Its value must be an integer, which specifies the
-number of seconds to wait before echoing. If the user types a prefix
-key (such as @kbd{C-x}) and then delays this many seconds before
-continuing, the prefix key is echoed in the echo area. Any subsequent
-characters in the same command will be echoed as well.
-
-If the value is zero, then command input is not echoed.
-@end defvar
-
@node Input Events
@section Input Events
@cindex events
describes the representation and meaning of input events in detail.
@defun eventp object
-This function returns non-@code{nil} if @var{event} is an input event.
+This function returns non-@code{nil} if @var{object} is an input event.
@end defun
@menu
* 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.
@table @asis
@item meta
-The 2**23 bit in the character code indicates a character
+The
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit in the character code indicates a character
typed with the meta key held down.
@item control
-The 2**22 bit in the character code indicates a non-@sc{ASCII}
+The
+@iftex
+$2^{26}$
+@end iftex
+@ifinfo
+2**26
+@end ifinfo
+bit in the character code indicates a non-@sc{ASCII}
control character.
@sc{ASCII} control characters such as @kbd{C-a} have special basic
But if you type a control combination not in @sc{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
-for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII}
+for @kbd{%} plus
+@iftex
+$2^{26}$
+@end iftex
+@ifinfo
+2**26
+@end ifinfo
+(assuming the terminal supports non-@sc{ASCII}
control characters).
@item shift
-The 2**21 bit in the character code indicates an @sc{ASCII} control
+The
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit in the character code indicates an @sc{ASCII} control
character typed with the shift key held down.
For letters, the basic code indicates upper versus lower case; for
digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within
the @sc{ASCII} character set whenever possible, Emacs avoids using
-the 2**21 bit for those characters.
+the
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit for those characters.
However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
-@kbd{C-a}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
+@kbd{C-a}, so Emacs uses the
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit in @kbd{C-A} and not in
@kbd{C-a}.
@item hyper
-The 2**20 bit in the character code indicates a character
+The
+@iftex
+$2^{24}$
+@end iftex
+@ifinfo
+2**24
+@end ifinfo
+bit in the character code indicates a character
typed with the hyper key held down.
@item super
-The 2**19 bit in the character code indicates a character
+The
+@iftex
+$2^{23}$
+@end iftex
+@ifinfo
+2**23
+@end ifinfo
+bit in the character code indicates a character
typed with the super key held down.
@item alt
-The 2**18 bit in the character code indicates a character typed with
+The
+@iftex
+$2^{22}$
+@end iftex
+@ifinfo
+2**22
+@end ifinfo
+bit in the character code indicates a character typed with
the alt key held down. (On some terminals, the key labeled @key{ALT}
is actually the meta key.)
@end table
- In the future, Emacs may support a larger range of basic codes. We
-may also move the modifier bits to larger bit numbers. Therefore, you
-should avoid mentioning specific bit numbers in your program.
-Instead, the way to test the modifier bits of a character is with the
-function @code{event-modifiers} (@pxref{Classifying Events}).
+ It is best to avoid mentioning specific bit numbers in your program.
+To test the modifier bits of a character, use the function
+@code{event-modifiers} (@pxref{Classifying Events}). When making key
+bindings, you can use the read syntax for characters with modifier bits
+(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
+@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
+specify the characters (@pxref{Changing Key Bindings}). The function
+@code{event-convert-list} converts such a list into an event type
+(@pxref{Classifying Events}).
@node Function Keys
@subsection Function Keys
so that the focus event comes either before or after the multi-event key
sequence, and not within it.
+@node Misc Events
+@subsection Miscellaneous Window System Events
+
+A few other event types represent occurrences within the window system.
+
+@table @code
+@cindex @code{delete-frame} event
+@item (delete-frame (@var{frame}))
+This kind of event indicates that the user gave the window manager
+a command to delete a particular window, which happens to be an Emacs frame.
+
+The standard definition of the @code{delete-frame} event is to delete @var{frame}.
+
+@cindex @code{iconify-frame} event
+@item (iconify-frame (@var{frame}))
+This kind of event indicates that the user iconified @var{frame} using
+the window manager. Its standard definition is @code{ignore}; since the
+frame has already been iconified, Emacs has no work to do. The purpose
+of this event type is so that you can keep track of such events if you
+want to.
+
+@cindex @code{make-frame-visible} event
+@item (make-frame-visible (@var{frame}))
+This kind of event indicates that the user deiconified @var{frame} using
+the window manager. Its standard definition is @code{ignore}; since the
+frame has already been made visible, Emacs has no work to do.
+@end table
+
+ If one of these events arrives in the middle of a key sequence---that
+is, after a prefix key---then Emacs reorders the events so that this
+event comes either before or after the multi-event key sequence, not
+within it.
+
@node Event Examples
@subsection Event Examples
event.
@end defun
+@defun event-convert-list list
+This function converts a list of modifier names and a basic event type
+to an event type which specifies all of them. For example,
+
+@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
@subsection Accessing Events
position such events have.
@end defun
- These four functions take a position as described above, and return
+ These five functions take a position as described above, and return
various parts of it.
@defun posn-window position
A keyboard character typed using the @key{META} key is called a
@dfn{meta character}. The numeric code for such an event includes the
-2**23 bit; it does not even come close to fitting in a string. However,
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit; it does not even come close to fitting in a string. However,
earlier Emacs versions used a different representation for these
characters, which gave them codes in the range of 128 to 255. That did
fit in a string, and many Lisp programs contain string constants that
in the string unchanged.
@item
-The meta variants of those characters, with codes in the range of 2**23
-to 2**23+127, can also go in the string, but you must change their
-numeric values. You must set the 2**7 bit instead of the 2**23 bit,
+The meta variants of those characters, with codes in the range of
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+to
+@iftex
+$2^{27} + 127$,
+@end iftex
+@ifinfo
+2**27+127,
+@end ifinfo
+can also go in the string, but you must change their
+numeric values. You must set the
+@iftex
+$2^{7}$
+@end iftex
+@ifinfo
+2**7
+@end ifinfo
+bit instead of the
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit,
resulting in a value between 128 and 255.
@item
The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
-button-down events entirely. It also reshuffles focus events so that they
-never appear in a key sequence with any other events.
+button-down events entirely. It also reshuffles focus events and
+miscellaneous window events so that they never appear in a key sequence
+with any other events.
When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special---it is the
defining key sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
-mouse on the window's mode line, you get an event like this:
+mouse on the window's mode line, you get two events, like this:
@example
(read-key-sequence "Click on the mode line: ")
@end group
@group
+;; @r{We assume here you use @kbd{M-:} to evaluate this.}
(symbol-function 'foo)
- @result{} "^[^[(read-char)^M1"
+ @result{} "^[:(read-char)^M1"
@end group
@group
(execute-kbd-macro 'foo)
In the example below, the Lisp program reads the character @kbd{1},
@sc{ASCII} code 49. It becomes the value of @code{last-input-event},
-while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this
-expression) remains the value of @code{last-command-event}.
+while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
+this expression) remains the value of @code{last-command-event}.
@example
@group
time with no input arriving (see @code{input-pending-p} in @ref{Event
Input Misc}). Otherwise, the value is @code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sit-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds. This adds to the period specified by
-@var{seconds}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+@var{seconds}. If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
@cindex forcing redisplay
Redisplay is always preempted if input arrives, and does not happen at
redisplay, but it still returns as soon as input is available (or when
the timeout elapses).
+Iconifying or deiconifying a frame makes @code{sit-for} return, because
+that generates an event. @xref{Misc Events}.
+
The usual purpose of @code{sit-for} is to give the user time to read
text that you display.
@end defun
the display. It pays no attention to available input. It returns
@code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sleep-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds. This adds to the period specified by
-@var{seconds}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+@var{seconds}. If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
Use @code{sleep-for} when you wish to guarantee a delay.
@end defun
been executed, to make it convenient to repeat these commands. A
@dfn{complex command} is one for which the interactive argument reading
uses the minibuffer. This includes any @kbd{M-x} command, any
-@kbd{M-ESC} command, and any command whose @code{interactive}
+@kbd{M-:} command, and any command whose @code{interactive}
specification reads an argument from the minibuffer. Explicit use of
the minibuffer during the execution of the command itself does not cause
the command to be considered complex.
encounters an error or a failing search.
@end defun
-@defvar last-kbd-macro
-This variable is the definition of the most recently defined keyboard
-macro. Its value is a string or vector, or @code{nil}.
-@end defvar
-
@defvar executing-macro
This variable contains the string or vector that defines the keyboard
macro that is currently executing. It is @code{nil} if no macro is
command can test this variable to behave differently while a macro is
being defined. The commands @code{start-kbd-macro} and
@code{end-kbd-macro} set this variable---do not set it yourself.
+
+The variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
+@end defvar
+
+@defvar last-kbd-macro
+This variable is the definition of the most recently defined keyboard
+macro. Its value is a string or vector, or @code{nil}.
+
+The variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
HCoop / bpt / emacs.git / blobdiff