@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/commands.info
@node Command Loop, Keymaps, Minibuffers, Top
When you run XEmacs, it enters the @dfn{editor command loop} almost
immediately. This loop reads events, executes their definitions,
and displays the results. In this chapter, we describe how these things
-are done, and the subroutines that allow Lisp programs to do them.
+are done, and the subroutines that allow Lisp programs to do them.
@menu
* Command Overview:: How the command loop reads commands.
@node Interactive Examples
@subsection Examples of Using @code{interactive}
@cindex examples of using @code{interactive}
-@cindex @code{interactive}, examples of using
+@cindex @code{interactive}, examples of using
Here are some examples of @code{interactive}:
reads the arguments and calls the command. You can also call these
functions yourself.
-@defun commandp object
-Returns @code{t} if @var{object} is suitable for calling interactively;
-that is, if @var{object} is a command. Otherwise, returns @code{nil}.
+@defun commandp function
+Returns @code{t} if @var{function} is suitable for calling interactively;
+that is, if @var{function} is a command. Otherwise, returns @code{nil}.
The interactively callable objects include strings and vectors (treated
as keyboard macros), lambda expressions that contain a top-level call to
realistic example of using @code{commandp}.
@end defun
-@defun call-interactively command &optional record-flag
+@defun call-interactively command &optional record-flag keys
This function calls the interactively callable function @var{command},
reading arguments according to its interactive calling specifications.
An error is signaled if @var{command} is not a function or if it cannot
@c XEmacs feature?
If @var{record-flag} is the symbol @code{lambda}, the interactive
-calling arguments for @code{command} are read and returned as a list,
+calling arguments for @var{command} are read and returned as a list,
but the function is not called on them.
@cindex record command history
an argument. @xref{Command History}.
@end defun
-@defun command-execute command &optional record-flag
+@defun command-execute command &optional record-flag keys
@cindex keyboard macro execution
This function executes @var{command} as an editing command. The
argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
@section Information from the Command Loop
The editor command loop sets several Lisp variables to keep status
-records for itself and for commands that are run.
+records for itself and for commands that are run.
@defvar last-command
This variable records the name of the previous command executed by the
@xref{Reading Input}.
@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
a portion of a frame needing to be redrawn) has occurred. The contents
of this event are not accessible at the E-Lisp level, but
@code{dispatch-event} knows what to do with an event of this type.
-
+
@item eval event
This is a special kind of event specifying that a particular function
needs to be called when this event is dispatched. An event of this type
This is true if @var{object} is a key-press event.
@end defun
-@defun button-event-p object object
+@defun button-event-p object
This is true if @var{object} is a mouse button-press or button-release
event.
@end defun
only for button-press and button-release events.
@item @code{modifiers}
-The event modifiers. This is a list of modifier symbols. It is allowed
+The event modifiers. This is a list of modifier symbols. It is allowed
for key-press, button-press, button-release and motion events.
@item @code{x}
@end defun
@defun copy-event event1 &optional event2
-This function makes a copy of the given event object. If a second
-argument is given, the first event is copied into the second and the
-second is returned. If the second argument is not supplied (or is
-@code{nil}) then a new event will be made.
+This function makes a copy of the event object @var{event1}. If a
+second event argument @var{event2} is given, @var{event1} is copied into
+@var{event2} and @var{event2} is returned. If @var{event2} is not
+supplied (or is @code{nil}) then a new event will be made, as with
+@code{make-event}.
@end defun
@defun deallocate-event event
it. You will lose. It is not necessary to call this function, as event
objects are garbage-collected like all other objects; however, it may be
more efficient to explicitly deallocate events when you are sure that
-that is safe.
+it is safe to do so.
@end defun
@node Converting Events
and other ways of representing keys. These are useful when working with
@sc{ascii} strings and with keymaps.
-@defun character-to-event ch &optional event device
-This function converts a numeric @sc{ascii} value to an event structure,
-replete with modifier bits. @var{ch} is the character to convert, and
+@defun character-to-event key-description &optional event console use-console-meta-flag
+This function converts a keystroke description to an event structure.
+@var{key-description} is the specification of a key stroke, and
@var{event} is the event object to fill in. This function contains
knowledge about what the codes ``mean''---for example, the number 9 is
converted to the character @key{Tab}, not the distinct character
@key{Control-I}.
-Note that @var{ch} does not have to be a numeric value, but can be a
-symbol such as @code{clear} or a list such as @code{(control
-backspace)}.
+Note that @var{key-description} can be an integer, a character, a symbol
+such as @code{clear} or a list such as @code{(control backspace)}.
+
+If optional arg @var{event} is non-@code{nil}, it is modified;
+otherwise, a new event object is created. In both cases, the event is
+returned.
-If @code{event} is not @code{nil}, it is modified; otherwise, a
-new event object is created. In both cases, the event is returned.
+Optional third arg @var{console} is the console to store in the event,
+and defaults to the selected console.
-Optional third arg @var{device} is the device to store in the event;
-this also affects whether the high bit is interpreted as a meta key. A
-value of @code{nil} means use the selected device but always treat the
-high bit as meta.
+If @var{key-description} is an integer or character, the high bit may be
+interpreted as the meta key. (This is done for backward compatibility in
+lots of places.) If @var{use-console-meta-flag} is @code{nil}, this
+will always be the case. If @var{use-console-meta-flag} is
+non-@code{nil}, the @code{meta} flag for @var{console} affects whether
+the high bit is interpreted as a meta key. (See @code{set-input-mode}.)
+If you don't want this silly meta interpretation done, you should pass
+in a list containing the character.
Beware that @code{character-to-event} and @code{event-to-character} are
not strictly inverse functions, since events contain much more
@code{read-key-sequence}; for example, @code{describe-key} uses it to
read the key to describe.
-@defun read-key-sequence prompt
+@defun read-key-sequence prompt &optional continue-echo dont-downcase-last
@cindex key sequence
This function reads a sequence of keystrokes or mouse clicks and returns
-it as a vector of events. It keeps reading events until it has
-accumulated a full key sequence; that is, enough to specify a non-prefix
-command using the currently active keymaps.
+it as a vector of event objects read. It keeps reading events until it
+has accumulated a full key sequence; that is, enough to specify a
+non-prefix command using the currently active keymaps.
-The vector and the event objects it contains are freshly created, and
-will not be side-effected by subsequent calls to this function.
+The vector and the event objects it contains are freshly created (and
+so will not be side-effected by subsequent calls to this function).
The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
typed while reading with this function works like any other character,
The argument @var{prompt} is either a string to be displayed in the echo
area as a prompt, or @code{nil}, meaning not to display a prompt.
+Second optional arg @var{continue-echo} non-@code{nil} means this key
+echoes as a continuation of the previous key.
+
+Third optional arg @var{dont-downcase-last} non-@code{nil} means do not
+convert the last event to lower case. (Normally any upper case event is
+converted to lower case if the original event is undefined and the lower
+case equivalent is defined.) This argument is provided mostly for
+@var{fsf} compatibility; the equivalent effect can be achieved more
+generally by binding @code{retry-undefined-key-binding-unshifted} to
+@code{nil} around the call to @code{read-key-sequence}.
+
@c XEmacs feature
If the user selects a menu item while we are prompting for a key
sequence, the returned value will be a vector of a single menu-selection
appropriate.
@end defun
-@defun next-command-event &optional event
+@defun next-command-event &optional event prompt
This function returns the next available ``user'' event from the window
system or terminal driver. Pass this object to @code{dispatch-event} to
handle it. If an event object is supplied, it is filled in and
For example, the function that implements numeric prefix arguments reads
any number of digits. When it finds a non-digit event, it must unread
the event so that it can be read normally by the command loop.
-Likewise, incremental search uses this feature to unread events with no
+Likewise, incremental search uses this feature to unread events with no
special meaning in a search, because these events should exit the search
and then execute normally.
In the following example, the user may type a number of characters right
after starting the evaluation of the form. After the @code{sleep-for}
-finishes sleeping, @code{discard-input} discards any characters typed
+finishes sleeping, @code{discard-input} discards any characters typed
during the sleep.
@example
value), instead of a single argument that can be either an integer or a
float.
-@defun sit-for seconds &optional nodisp
+@defun sit-for seconds &optional nodisplay
This function performs redisplay (provided there is no pending input
from the user), then waits @var{seconds} seconds, or until input is
available. The result is @code{t} if @code{sit-for} waited the full
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.
-@ignore FSF Emacs stuff
-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}. If the system doesn't support waiting fractions of a
-second, you get an error if you specify nonzero @var{millisec}.
-@end ignore
@cindex forcing redisplay
Redisplay is normally preempted if input arrives, and does not happen at
Screen}.) If there is no input pending, you can force an update with no
delay by using @code{(sit-for 0)}.
-If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
+If @var{nodisplay} is non-@code{nil}, then @code{sit-for} does not
redisplay, but it still returns as soon as input is available (or when
the timeout elapses).
At the level of C code, quitting cannot happen just anywhere; only at the
special places that check @code{quit-flag}. The reason for this is
that quitting at other places might leave an inconsistency in XEmacs's
-internal state. Because quitting is delayed until a safe place, quitting
+internal state. Because quitting is delayed until a safe place, quitting
cannot make XEmacs crash.
Certain functions such as @code{read-key-sequence} or
input. In the case of @code{read-key-sequence}, this serves to bring
about the special behavior of @kbd{C-g} in the command loop. In the
case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
-to quote a @kbd{C-g}.
+to quote a @kbd{C-g}.
You can prevent quitting for a portion of a Lisp function by binding
the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
You can specify a character other than @kbd{C-g} to use for quitting.
See the function @code{set-input-mode} in @ref{Terminal Input}.
-
+
@node Prefix Command Arguments
@section Prefix Command Arguments
@cindex prefix argument
C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
-C-u - M-x display-prefix @print{} -
+C-u - M-x display-prefix @print{} -
M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
-C-u - 7 M-x display-prefix @print{} -7
+C-u - 7 M-x display-prefix @print{} -7
M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
value of the prefix argument directly in the variable
@code{current-prefix-arg}, but this is less clean.
-@defun prefix-numeric-value arg
+@defun prefix-numeric-value raw
This function returns the numeric meaning of a valid raw prefix argument
-value, @var{arg}. The argument may be a symbol, a number, or a list.
+value, @var{raw}. The argument may be a symbol, a number, or a list.
If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
value @minus{}1 is returned; if it is a number, that number is returned;
if it is a list, the @sc{car} of that list (which should be a number) is
Recursive editing levels are also used when you type @kbd{C-r} in
@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
-@defun recursive-edit
+@deffn Command recursive-edit
@cindex suspend evaluation
This function invokes the editor command loop. It is called
automatically by the initialization of XEmacs, to let the user begin
(simple-rec)
@result{} nil
@end example
-@end defun
+@end deffn
@deffn Command exit-recursive-edit
This function exits from the innermost recursive edit (including
minibuffer input). Its definition is effectively @code{(throw 'exit
-nil)}.
+nil)}.
@end deffn
@deffn Command abort-recursive-edit
This function aborts the command that requested the innermost recursive
-edit (including minibuffer input), by signaling @code{quit}
+edit (including minibuffer input), by signaling @code{quit}
after exiting the recursive edit. Its definition is effectively
@code{(throw 'exit t)}. @xref{Quitting}.
@end deffn
The argument @var{count} is a repeat count; @var{macro} is executed that
many times. If @var{count} is omitted or @code{nil}, @var{macro} is
executed once. If it is 0, @var{macro} is executed over and over until it
-encounters an error or a failing search.
+encounters an error or a failing search.
@end defun
@defvar executing-macro
projects / chise / xemacs-chise.git.1 / blobdiff