-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
+
+Interactive Call
+================
+
+ After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+`command-execute'. If the definition is a function that is a command,
+`command-execute' calls `call-interactively', which reads the arguments
+and calls the command. You can also call these functions yourself.
+
+ - Function: commandp object
+ Returns `t' if OBJECT is suitable for calling interactively; that
+ is, if OBJECT is a command. Otherwise, returns `nil'.
+
+ The interactively callable objects include strings and vectors
+ (treated as keyboard macros), lambda expressions that contain a
+ top-level call to `interactive', compiled-function objects made
+ from such lambda expressions, autoload objects that are declared
+ as interactive (non-`nil' fourth argument to `autoload'), and some
+ of the primitive functions.
+
+ A symbol is `commandp' if its function definition is `commandp'.
+
+ Keys and keymaps are not commands. Rather, they are used to look
+ up commands (*note Keymaps::).
+
+ See `documentation' in *Note Accessing Documentation::, for a
+ realistic example of using `commandp'.
+
+ - Function: call-interactively command &optional record-flag
+ This function calls the interactively callable function COMMAND,
+ reading arguments according to its interactive calling
+ specifications. An error is signaled if COMMAND is not a function
+ or if it cannot be called interactively (i.e., is not a command).
+ Note that keyboard macros (strings and vectors) are not accepted,
+ even though they are considered commands, because they are not
+ functions.
+
+ If RECORD-FLAG is the symbol `lambda', the interactive calling
+ arguments for `command' are read and returned as a list, but the
+ function is not called on them.
+
+ If RECORD-FLAG is `t', then this command and its arguments are
+ unconditionally added to the list `command-history'. Otherwise,
+ the command is added only if it uses the minibuffer to read an
+ argument. *Note Command History::.
+
+ - Function: command-execute command &optional record-flag
+ This function executes COMMAND as an editing command. The
+ argument COMMAND must satisfy the `commandp' predicate; i.e., it
+ must be an interactively callable function or a keyboard macro.
+
+ A string or vector as COMMAND is executed with
+ `execute-kbd-macro'. A function is passed to
+ `call-interactively', along with the optional RECORD-FLAG.
+
+ A symbol is handled by using its function definition in its place.
+ A symbol with an `autoload' definition counts as a command if it
+ was declared to stand for an interactively callable function.
+ Such a definition is handled by loading the specified library and
+ then rechecking the definition of the symbol.
+
+ - Command: execute-extended-command prefix-argument
+ This function reads a command name from the minibuffer using
+ `completing-read' (*note Completion::). Then it uses
+ `command-execute' to call the specified command. Whatever that
+ command returns becomes the value of `execute-extended-command'.
+
+ If the command asks for a prefix argument, it receives the value
+ PREFIX-ARGUMENT. If `execute-extended-command' is called
+ interactively, the current raw prefix argument is used for
+ PREFIX-ARGUMENT, and thus passed on to whatever command is run.
+
+ `execute-extended-command' is the normal definition of `M-x', so
+ it uses the string `M-x ' as a prompt. (It would be better to
+ take the prompt from the events used to invoke
+ `execute-extended-command', but that is painful to implement.) A
+ description of the value of the prefix argument, if any, also
+ becomes part of the prompt.
+
+ (execute-extended-command 1)
+ ---------- Buffer: Minibuffer ----------
+ 1 M-x forward-word RET
+ ---------- Buffer: Minibuffer ----------
+ => t
+
+ - Function: interactive-p
+ This function returns `t' if the containing function (the one that
+ called `interactive-p') was called interactively, with the function
+ `call-interactively'. (It makes no difference whether
+ `call-interactively' was called from Lisp or directly from the
+ editor command loop.) If the containing function was called by
+ Lisp evaluation (or with `apply' or `funcall'), then it was not
+ called interactively.
+
+ The most common use of `interactive-p' is for deciding whether to
+ print an informative message. As a special exception,
+ `interactive-p' returns `nil' whenever a keyboard macro is being
+ run. This is to suppress the informative messages and speed
+ execution of the macro.
+
+ For example:
+
+ (defun foo ()
+ (interactive)
+ (and (interactive-p)
+ (message "foo")))
+ => foo
+
+ (defun bar ()
+ (interactive)
+ (setq foobar (list (foo) (interactive-p))))
+ => bar
+
+ ;; Type `M-x foo'.
+ -| foo
+
+ ;; Type `M-x bar'.
+ ;; This does not print anything.
+
+ foobar
+ => (nil t)
+
+\1f
File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
Information from the Command Loop
is the nearest character equivalent to it (or `nil' if there is no
character equivalent). `last-command-char' is the character that
`self-insert-command' will insert in the buffer. Remember that
- there is *not* a one-to-one mapping between keyboard events and
+ there is _not_ a one-to-one mapping between keyboard events and
XEmacs characters: many keyboard events have no corresponding
character, and when the Mule feature is available, most characters
can not be input on standard keyboards, except possibly with help
For information about how exactly the XEmacs command loop works,
*Note Reading Input::.
- - Function: eventp OBJECT
+ - Function: eventp object
This function returns non-`nil' if EVENT is an input event.
* Menu:
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
x
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
misc-user event
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
x
The object to pass to the function. The function and object
are set when the event is created.
- - Function: event-type EVENT
+ - Function: event-type event
Return the type of EVENT.
This will be a symbol; one of
The following predicates return whether an object is an event of a
particular type.
- - Function: key-press-event-p OBJECT
+ - Function: key-press-event-p object
This is true if OBJECT is a key-press event.
- - Function: button-event-p OBJECT OBJECT
+ - Function: button-event-p object object
This is true if OBJECT is a mouse button-press or button-release
event.
- - Function: button-press-event-p OBJECT
+ - Function: button-press-event-p object
This is true if OBJECT is a mouse button-press event.
- - Function: button-release-event-p OBJECT
+ - Function: button-release-event-p object
This is true if OBJECT is a mouse button-release event.
- - Function: motion-event-p OBJECT
+ - Function: motion-event-p object
This is true if OBJECT is a mouse motion event.
- - Function: mouse-event-p OBJECT
+ - Function: mouse-event-p object
This is true if OBJECT is a mouse button-press, button-release or
motion event.
- - Function: eval-event-p OBJECT
+ - Function: eval-event-p object
This is true if OBJECT is an eval event.
- - Function: misc-user-event-p OBJECT
+ - Function: misc-user-event-p object
This is true if OBJECT is a misc-user event.
- - Function: process-event-p OBJECT
+ - Function: process-event-p object
This is true if OBJECT is a process event.
- - Function: timeout-event-p OBJECT
+ - Function: timeout-event-p object
This is true if OBJECT is a timeout event.
- - Function: event-live-p OBJECT
+ - Function: event-live-p object
This is true if OBJECT is any event that has not been deallocated.
\1f
The following functions return frame-level information about where a
mouse event occurred.
- - Function: event-frame EVENT
+ - Function: event-frame event
This function returns the "channel" or frame that the given mouse
motion, button press, button release, or misc-user event occurred
in. This will be `nil' for non-mouse events.
- - Function: event-x-pixel EVENT
+ - Function: event-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
mouse event.
- - Function: event-y-pixel EVENT
+ - Function: event-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
The following functions return window-level information about where
a mouse event occurred.
- - Function: event-window EVENT
+ - Function: event-window event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the window on which that event occurred.
This may be `nil' if the event occurred in the border or over a
toolbar. The modeline is considered to be within the window it
describes.
- - Function: event-buffer EVENT
+ - Function: event-buffer event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the buffer of the window on which that
event occurred. This may be `nil' if the event occurred in the
`event-window' and then calling `window-buffer' on the result if
it is a window.
- - Function: event-window-x-pixel EVENT
+ - Function: event-window-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
mouse-motion, button-press, button-release, or misc-user event.
- - Function: event-window-y-pixel EVENT
+ - Function: event-window-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
The following functions return information about the text (including
the modeline) that a mouse event occurred over or near.
- - Function: event-over-text-area-p EVENT
+ - Function: event-over-text-area-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the text
area of a window. Otherwise, `nil' is returned. The modeline is
not considered to be part of the text area.
- - Function: event-over-modeline-p EVENT
+ - Function: event-over-modeline-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the modeline
of a window. Otherwise, `nil' is returned.
- - Function: event-x EVENT
+ - Function: event-x event
This function returns the X position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-y EVENT
+ - Function: event-y event
This function returns the Y position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-point EVENT
+ - Function: event-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window, or did not occur over
text, then this returns `nil'. Otherwise, it returns an index
into the buffer visible in the event's window.
- - Function: event-closest-point EVENT
+ - Function: event-closest-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window or over text, it returns
The following functions return information about the glyph (if any)
that a mouse event occurred over.
- - Function: event-over-glyph-p EVENT
+ - Function: event-over-glyph-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a glyph.
Otherwise, `nil' is returned.
- - Function: event-glyph-extent EVENT
+ - Function: event-glyph-extent event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a glyph, this returns its
extent; else `nil' is returned.
- - Function: event-glyph-x-pixel EVENT
+ - Function: event-glyph-x-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the X position of the
pointer relative to the upper left of the glyph. If the event is
not over a glyph, it returns `nil'.
- - Function: event-glyph-y-pixel EVENT
+ - Function: event-glyph-y-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the Y position of the
pointer relative to the upper left of the glyph. If the event is
Event Toolbar Position Info
...........................
- - Function: event-over-toolbar-p EVENT
+ - Function: event-over-toolbar-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a toolbar.
Otherwise, `nil' is returned.
- - Function: event-toolbar-button EVENT
+ - Function: event-toolbar-button event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a toolbar button, this function
returns the button. Otherwise, `nil' is returned.
Other Event Position Info
.........................
- - Function: event-over-border-p EVENT
+ - Function: event-over-border-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over an internal
toolbar. Otherwise, `nil' is returned.
The following functions allow access to the contents of events other
than the position info described in the previous section.
- - Function: event-timestamp EVENT
+ - Function: event-timestamp event
This function returns the timestamp of the given event object.
- - Function: event-device EVENT
+ - Function: event-device event
This function returns the device that the given event occurred on.
- - Function: event-key EVENT
+ - Function: event-key event
This function returns the Keysym of the given key-press event.
This will be the ASCII code of a printing character, or a symbol.
- - Function: event-button EVENT
+ - Function: event-button event
This function returns the button-number of the given button-press
or button-release event.
- - Function: event-modifiers EVENT
+ - Function: event-modifiers event
This function returns a list of symbols, the names of the modifier
keys which were down when the given mouse or keyboard event was
produced.
- - Function: event-modifier-bits EVENT
+ - Function: event-modifier-bits event
This function returns a number representing the modifier keys
which were down when the given mouse or keyboard event was
produced.
- - Function: event-function EVENT
+ - Function: event-function event
This function returns the callback function of the given timeout,
misc-user, or eval event.
- - Function: event-object EVENT
+ - Function: event-object event
This function returns the callback function argument of the given
timeout, misc-user, or eval event.
- - Function: event-process EVENT
+ - Function: event-process event
This function returns the process of the given process event.
\1f
either an event object or `nil', creating the event object first in the
latter case.
- - Function: make-event &optional TYPE PLIST
+ - Function: make-event &optional type plist
This function creates a new event structure. If no arguments are
specified, the created event will be empty. To specify the event
type, use the TYPE argument. The allowed types are `empty',
The event timestamp, a non-negative integer. Allowed for all
types of events.
- *WARNING*: the event object returned by this function may be a
+ _WARNING_: the event object returned by this function may be a
reused one; see the function `deallocate-event'.
The events created by `make-event' can be used as non-interactive
;; Create an empty event.
(make-event)
=> #<empty-event>
-
+
;; Try creating a key-press event.
(make-event 'key-press)
error--> Undefined key for keypress event
-
+
;; Creating a key-press event, try 2
(make-event 'key-press '(key home))
=> #<keypress-event home>
-
+
;; Create a key-press event of dubious fame.
(make-event 'key-press '(key escape modifiers (meta alt control shift)))
=> #<keypress-event control-meta-alt-shift-escape>
-
+
;; Create a M-button1 event at coordinates defined by variables
;; X and Y.
(make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
=> #<buttondown-event meta-button1>
-
+
;; Create a similar button-release event.
(make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
=> #<buttonup-event meta-button1up>
-
+
;; Create a mouse-motion event.
(make-event 'motion '(x 20 y 30))
=> #<motion-event 20, 30>
(append '(modifiers nil)
(event-properties EVENT)))
- - Function: copy-event EVENT1 &optional EVENT2
+ - Function: 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 `nil') then a new event will be made.
- - Function: deallocate-event EVENT
+ - Function: deallocate-event event
This function allows the given event structure to be reused. You
*MUST NOT* use this event object after calling this function with
it. You will lose. It is not necessary to call this function, as
events and other ways of representing keys. These are useful when
working with ASCII strings and with keymaps.
- - Function: character-to-event CH &optional EVENT DEVICE
+ - Function: character-to-event ch &optional event device
This function converts a numeric ASCII value to an event structure,
replete with modifier bits. CH is the character to convert, and
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 <Tab>, not the distinct character
+ knowledge about what the codes "mean"--for example, the number 9 is
+ converted to the character <Tab>, not the distinct character
<Control-I>.
Note that CH does not have to be a numeric value, but can be a
strictly inverse functions, since events contain much more
information than the ASCII character set can encode.
- - Function: event-to-character EVENT &optional ALLOW-EXTRA-MODIFIERS
- ALLOW-META ALLOW-NON-ASCII
+ - Function: event-to-character event &optional allow-extra-modifiers
+ allow-meta allow-non-ascii
This function returns the closest ASCII approximation to EVENT.
If the event isn't a keypress, this returns `nil'.
ambiguous, as both use the high bit; <M-x> and <oslash> will be
indistinguishable.
- - Function: events-to-keys EVENTS &optional NO-MICE
+ - Function: events-to-keys events &optional no-mice
Given a vector of event objects, this function returns a vector of
key descriptors, or a string (if they all fit in the ASCII range).
Optional arg NO-MICE means that button events are not allowed.
`read-key-sequence'; for example, `describe-key' uses it to read the
key to describe.
- - Function: read-key-sequence PROMPT
+ - Function: read-key-sequence prompt
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
actions), and other events, which serve as communication between XEmacs
and the window system.
- - Function: next-event &optional EVENT PROMPT
+ - Function: next-event &optional event prompt
This function reads and returns the next available event from the
window system or terminal driver, waiting if necessary until an
event is available. Pass this object to `dispatch-event' to
In most cases, the function `next-command-event' is more
appropriate.
- - Function: next-command-event &optional EVENT
+ - Function: next-command-event &optional event
This function returns the next available "user" event from the
window system or terminal driver. Pass this object to
`dispatch-event' to handle it. If an event object is supplied, it
`dispatch-event') and discarded. This function is provided as a
convenience; it is equivalent to the Lisp code
- (while (progn
- (next-event event)
- (not (or (key-press-event-p event)
- (button-press-event-p event)
- (button-release-event-p event)
- (menu-event-p event))))
- (dispatch-event event))
+ (while (progn
+ (next-event event)
+ (not (or (key-press-event-p event)
+ (button-press-event-p event)
+ (button-release-event-p event)
+ (menu-event-p event))))
+ (dispatch-event event))
Here is what happens if you call `next-command-event' and then
press the right-arrow function key:
compatibility with Emacs 18, and is most likely the wrong thing
for you to be using: consider using `next-command-event' instead.
- - Function: enqueue-eval-event FUNCTION OBJECT
+ - Function: enqueue-eval-event function object
This function adds an eval event to the back of the queue. The
eval event will be the next event read after all pending events.
Dispatching an Event
--------------------
- - Function: dispatch-event EVENT
+ - Function: dispatch-event event
Given an event object returned by `next-event', this function
executes it. This is the basic function that makes XEmacs respond
to user input; it also deals with notifications from the window
character conveniently, either literally or as an octal character code.
The command `quoted-insert' uses this function.
- - Function: read-quoted-char &optional PROMPT
+ - Function: read-quoted-char &optional prompt
This function is like `read-char', except that if the first
character read is an octal digit (0-7), it reads up to two more
octal digits (but stopping if a non-octal digit is found) and
- Variable: last-input-char
If the value of `last-input-event' is a keyboard event, then this
is the nearest ASCII equivalent to it. Remember that there is
- *not* a 1:1 mapping between keyboard events and ASCII characters:
+ _not_ a 1:1 mapping between keyboard events and ASCII characters:
the set of keyboard events is much larger, so writing code that
examines this variable to determine what key has been typed is bad
practice, unless you are certain that it will be one of a small
(discard-input))
=> nil
-\1f
-File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
-
-Waiting for Elapsed Time or Input
-=================================
-
- The wait functions are designed to wait for a certain amount of time
-to pass or until there is input. For example, you may wish to pause in
-the middle of a computation to allow the user time to view the display.
-`sit-for' pauses and updates the screen, and returns immediately if
-input comes in, while `sleep-for' pauses without updating the screen.
-
- Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
-two arguments to specify the time (one integer and one float value),
-instead of a single argument that can be either an integer or a float.
-
- - Function: sit-for SECONDS &optional NODISP
- This function performs redisplay (provided there is no pending
- input from the user), then waits SECONDS seconds, or until input is
- available. The result is `t' if `sit-for' waited the full time
- with no input arriving (see `input-pending-p' in *Note Peeking and
- Discarding::). Otherwise, the value is `nil'.
-
- The argument SECONDS need not be an integer. If it is a floating
- point number, `sit-for' waits for a fractional number of seconds.
-
- Redisplay is normally preempted if input arrives, and does not
- happen at all if input is available before it starts. (You can
- force screen updating in such a case by using `force-redisplay'.
- *Note Refresh Screen::.) If there is no input pending, you can
- force an update with no delay by using `(sit-for 0)'.
-
- If NODISP is non-`nil', then `sit-for' does not redisplay, but it
- still returns as soon as input is available (or when the timeout
- elapses).
-
- The usual purpose of `sit-for' is to give the user time to read
- text that you display.
-
- - Function: sleep-for SECONDS
- This function simply pauses for SECONDS seconds without updating
- the display. This function pays no attention to available input.
- It returns `nil'.
-
- The argument SECONDS need not be an integer. If it is a floating
- point number, `sleep-for' waits for a fractional number of seconds.
-
- Use `sleep-for' when you wish to guarantee a delay.
-
- *Note Time of Day::, for functions to get the current time.
-
projects / chise / xemacs-chise.git- / blobdiff