-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.0b 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: Using Interactive, Next: Interactive Codes, Up: Defining Commands
+
+Using `interactive'
+-------------------
+
+ This section describes how to write the `interactive' form that
+makes a Lisp function an interactively-callable command.
+
+ - Special Form: interactive arg-descriptor
+ This special form declares that the function in which it appears
+ is a command, and that it may therefore be called interactively
+ (via `M-x' or by entering a key sequence bound to it). The
+ argument ARG-DESCRIPTOR declares how to compute the arguments to
+ the command when the command is called interactively.
+
+ A command may be called from Lisp programs like any other
+ function, but then the caller supplies the arguments and
+ ARG-DESCRIPTOR has no effect.
+
+ The `interactive' form has its effect because the command loop
+ (actually, its subroutine `call-interactively') scans through the
+ function definition looking for it, before calling the function.
+ Once the function is called, all its body forms including the
+ `interactive' form are executed, but at this time `interactive'
+ simply returns `nil' without even evaluating its argument.
+
+ There are three possibilities for the argument ARG-DESCRIPTOR:
+
+ * It may be omitted or `nil'; then the command is called with no
+ arguments. This leads quickly to an error if the command requires
+ one or more arguments.
+
+ * It may be a Lisp expression that is not a string; then it should
+ be a form that is evaluated to get a list of arguments to pass to
+ the command.
+
+ 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 _not_ to do:
+
+ (interactive
+ (list (region-beginning) (region-end)
+ (read-string "Foo: " nil 'my-history)))
+
+ Here's how to avoid the problem, by examining point and the mark
+ only after reading the keyboard input:
+
+ (interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+ (list (region-beginning) (region-end) string)))
+
+ * It may be a string; then its contents should consist of a code
+ character followed by a prompt (which some code characters use and
+ some ignore). The prompt ends either with the end of the string
+ or with a newline. Here is a simple example:
+
+ (interactive "bFrobnicate buffer: ")
+
+ The code letter `b' says to read the name of an existing buffer,
+ with completion. The buffer name is the sole argument passed to
+ the command. The rest of the string is a prompt.
+
+ If there is a newline character in the string, it terminates the
+ prompt. If the string does not end there, then the rest of the
+ string should contain another code character and prompt,
+ specifying another argument. You can specify any number of
+ arguments in this way.
+
+ The prompt string can use `%' to include previous argument values
+ (starting with the first argument) in the prompt. This is done
+ using `format' (*note Formatting Strings::). For example, here is
+ how you could read the name of an existing buffer followed by a
+ new name to give to that buffer:
+
+ (interactive "bBuffer to rename: \nsRename buffer %s to: ")
+
+ If the first character in the string is `*', then an error is
+ signaled if the buffer is read-only.
+
+ If the first character in the string is `@', and if the key
+ sequence used to invoke the command includes any mouse events, then
+ the window associated with the first of those events is selected
+ before the command is run.
+
+ If the first character in the string is `_', then this command will
+ not cause the region to be deactivated when it completes; that is,
+ `zmacs-region-stays' will be set to `t' when the command exits
+ successfully.
+
+ You can use `*', `@', and `_' together; the order does not matter.
+ Actual reading of arguments is controlled by the rest of the
+ prompt string (starting with the first character that is not `*',
+ `@', or `_').
+
+ - Function: function-interactive function
+ This function retrieves the interactive specification of FUNCTION,
+ which may be any funcallable object. The specification will be
+ returned as the list of the symbol `interactive' and the specs. If
+ FUNCTION is not interactive, `nil' will be returned.
+
+\1f
+File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
+
+Code Characters for `interactive'
+---------------------------------
+
+ The code character descriptions below contain a number of key words,
+defined here as follows:
+
+Completion
+ Provide completion. <TAB>, <SPC>, and <RET> perform name
+ completion because the argument is read using `completing-read'
+ (*note Completion::). `?' displays a list of possible completions.
+
+Existing
+ Require the name of an existing object. An invalid name is not
+ accepted; the commands to exit the minibuffer do not exit if the
+ current input is not valid.
+
+Default
+ A default value of some sort is used if the user enters no text in
+ the minibuffer. The default depends on the code character.
+
+No I/O
+ This code letter computes an argument without reading any input.
+ Therefore, it does not use a prompt string, and any prompt string
+ you supply is ignored.
+
+ Even though the code letter doesn't use a prompt string, you must
+ follow it with a newline if it is not the last code character in
+ the string.
+
+Prompt
+ A prompt immediately follows the code character. The prompt ends
+ either with the end of the string or with a newline.
+
+Special
+ This code character is meaningful only at the beginning of the
+ interactive string, and it does not look for a prompt or a newline.
+ It is a single, isolated character.
+
+ Here are the code character descriptions for use with `interactive':
+
+`*'
+ Signal an error if the current buffer is read-only. Special.
+
+`@'
+ Select the window mentioned in the first mouse event in the key
+ sequence that invoked this command. Special.
+
+`_'
+ Do not cause the region to be deactivated when this command
+ completes. Special.
+
+`a'
+ A function name (i.e., a symbol satisfying `fboundp'). Existing,
+ Completion, Prompt.
+
+`b'
+ The name of an existing buffer. By default, uses the name of the
+ current buffer (*note Buffers::). Existing, Completion, Default,
+ Prompt.
+
+`B'
+ A buffer name. The buffer need not exist. By default, uses the
+ name of a recently used buffer other than the current buffer.
+ Completion, Default, Prompt.
+
+`c'
+ A character. The cursor does not move into the echo area. Prompt.
+
+`C'
+ A command name (i.e., a symbol satisfying `commandp'). Existing,
+ Completion, Prompt.
+
+`d'
+ The position of point, as an integer (*note Point::). No I/O.
+
+`D'
+ A directory name. The default is the current default directory of
+ the current buffer, `default-directory' (*note System
+ Environment::). Existing, Completion, Default, Prompt.
+
+`e'
+ The last mouse-button or misc-user event in the key sequence that
+ invoked the command. No I/O.
+
+ You can use `e' more than once in a single command's interactive
+ specification. If the key sequence that invoked the command has N
+ mouse-button or misc-user events, the Nth `e' provides the Nth
+ such event.
+
+`f'
+ A file name of an existing file (*note File Names::). The default
+ directory is `default-directory'. Existing, Completion, Default,
+ Prompt.
+
+`F'
+ A file name. The file need not exist. Completion, Default,
+ Prompt.
+
+`k'
+ A key sequence (*note Keymap Terminology::). This keeps reading
+ events until a command (or undefined command) is found in the
+ current key maps. The key sequence argument is represented as a
+ vector of events. The cursor does not move into the echo area.
+ Prompt.
+
+ This kind of input is used by commands such as `describe-key' and
+ `global-set-key'.
+
+`K'
+ A key sequence, whose definition you intend to change. This works
+ like `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.
+
+`m'
+ The position of the mark, as an integer. No I/O.
+
+`n'
+ A number read with the minibuffer. If the input is not a number,
+ the user is asked to try again. The prefix argument, if any, is
+ not used. Prompt.
+
+`N'
+ The raw prefix argument. If the prefix argument is `nil', then
+ read a number as with `n'. Requires a number. *Note Prefix
+ Command Arguments::. Prompt.
+
+`p'
+ The numeric prefix argument. (Note that this `p' is lower case.)
+ No I/O.
+
+`P'
+ The raw prefix argument. (Note that this `P' is upper case.) No
+ I/O.
+
+`r'
+ Point and the mark, as two numeric arguments, smallest first.
+ This is the only code letter that specifies two successive
+ arguments rather than one. No I/O.
+
+`s'
+ Arbitrary text, read in the minibuffer and returned as a string
+ (*note Text from Minibuffer::). Terminate the input with either
+ <LFD> or <RET>. (`C-q' may be used to include either of these
+ characters in the input.) Prompt.
+
+`S'
+ An interned symbol whose name is read in the minibuffer. Any
+ whitespace character terminates the input. (Use `C-q' to include
+ whitespace in the string.) Other characters that normally
+ terminate a symbol (e.g., parentheses and brackets) do not do so
+ here. Prompt.
+
+`v'
+ A variable declared to be a user option (i.e., satisfying the
+ predicate `user-variable-p'). *Note High-Level Completion::.
+ Existing, Completion, Prompt.
+
+`x'
+ A Lisp object, specified with its read syntax, terminated with a
+ <LFD> or <RET>. The object is not evaluated. *Note Object from
+ Minibuffer::. Prompt.
+
+`X'
+ A Lisp form is read as with `x', but then evaluated so that its
+ value becomes the argument for the command. Prompt.
+
+\1f
+File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
+
+Examples of Using `interactive'
+-------------------------------
+
+ Here are some examples of `interactive':
+
+ (defun foo1 () ; `foo1' takes no arguments,
+ (interactive) ; just moves forward two words.
+ (forward-word 2))
+ => foo1
+
+ (defun foo2 (n) ; `foo2' takes one argument,
+ (interactive "p") ; which is the numeric prefix.
+ (forward-word (* 2 n)))
+ => foo2
+
+ (defun foo3 (n) ; `foo3' takes one argument,
+ (interactive "nCount:") ; which is read with the Minibuffer.
+ (forward-word (* 2 n)))
+ => foo3
+
+ (defun three-b (b1 b2 b3)
+ "Select three existing buffers.
+ Put them into three windows, selecting the last one."
+ (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))
+ => three-b
+ (three-b "*scratch*" "declarations.texi" "*mail*")
+ => nil
+
+\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 function
+ Returns `t' if FUNCTION is suitable for calling interactively;
+ that is, if FUNCTION 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 keys
+ 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 keys
+ 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
- This function returns non-`nil' if EVENT is an input event.
+ - Function: eventp object
+ This function returns non-`nil' if OBJECT 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
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
- 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: copy-event event1 &optional event2
+ This function makes a copy of the event object EVENT1. If a
+ second event argument EVENT2 is given, EVENT1 is copied into
+ EVENT2 and EVENT2 is returned. If EVENT2 is not supplied (or is
+ `nil') then a new event will be made, as with `make-event'.
- - 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
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.
-
-\1f
-File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
-
-Converting Events
------------------
-
- XEmacs provides some auxiliary functions for converting between
-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
- 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
- <Control-I>.
-
- Note that CH does not have to be a numeric value, but can be a
- symbol such as `clear' or a list such as `(control backspace)'.
-
- If `event' is not `nil', it is modified; otherwise, a new event
- object is created. In both cases, the event is returned.
-
- Optional third arg 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 `nil' means use the selected device but always
- treat the high bit as meta.
-
- Beware that `character-to-event' and `event-to-character' are not
- 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
- This function returns the closest ASCII approximation to EVENT.
- If the event isn't a keypress, this returns `nil'.
-
- If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
- translation; it will ignore modifier keys other than <control> and
- <meta>, and will ignore the <shift> modifier on those characters
- which have no shifted ASCII equivalent (<Control-Shift-A> for
- example, will be mapped to the same ASCII code as <Control-A>).
-
- If ALLOW-META is non-`nil', then the <Meta> modifier will be
- represented by turning on the high bit of the byte returned;
- otherwise, `nil' will be returned for events containing the <Meta>
- modifier.
-
- If ALLOW-NON-ASCII is non-`nil', then characters which are present
- in the prevailing character set (*note variable
- `character-set-property': Keymaps.) will be returned as their code
- in that character set, instead of the return value being
- restricted to ASCII.
-
- Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
- ambiguous, as both use the high bit; <M-x> and <oslash> will be
- indistinguishable.
-
- - 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.
-
-\1f
-File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
-
-Reading Input
-=============
-
- The editor command loop reads keyboard input using the function
-`next-event' and constructs key sequences out of the events using
-`dispatch-event'. Lisp programs can also use the function
-`read-key-sequence', which reads input a key sequence at a time. See
-also `momentary-string-display' in *Note Temporary Displays::, and
-`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions
-and variables for controlling terminal input modes and debugging
-terminal input.
-
- For higher-level input facilities, see *Note Minibuffers::.
-
-* Menu:
-
-* Key Sequence Input:: How to read one key sequence.
-* Reading One Event:: How to read just one event.
-* Dispatching an Event:: What to do with an event once it has been read.
-* Quoted Character Input:: Asking the user to specify a character.
-* Peeking and Discarding:: How to reread or throw away input events.
-
-\1f
-File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
-
-Key Sequence Input
-------------------
-
- Lisp programs can read input a key sequence at a time by calling
-`read-key-sequence'; for example, `describe-key' uses it to read the
-key to describe.
-
- - 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
- 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 function `read-key-sequence' suppresses quitting: `C-g' typed
- while reading with this function works like any other character,
- and does not set `quit-flag'. *Note Quitting::.
-
- The argument PROMPT is either a string to be displayed in the echo
- area as a prompt, or `nil', meaning not to display a prompt.
-
- 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 event (a misc-user event). An error will be
- signalled if you pass this value to `lookup-key' or a related
- function.
-
- In the example below, the prompt `?' is displayed in the echo area,
- and the user types `C-x C-f'.
-
- (read-key-sequence "?")
-
- ---------- Echo Area ----------
- ?C-x C-f
- ---------- Echo Area ----------
-
- => [#<keypress-event control-X> #<keypress-event control-F>]
-
- If an input character is an upper-case letter and has no key binding,
-but its lower-case equivalent has one, then `read-key-sequence'
-converts the character to lower case. Note that `lookup-key' does not
-perform case conversion in this way.
-
-\1f
-File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
-
-Reading One Event
------------------
-
- The lowest level functions for command input are those which read a
-single event. These functions often make a distinction between
-"command events", which are user actions (keystrokes and mouse
-actions), and other events, which serve as communication between XEmacs
-and the window system.
-
- - 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
- handle it. If an event object is supplied, it is filled in and
- returned; otherwise a new event object will be created.
-
- Events can come directly from the user, from a keyboard macro, or
- from `unread-command-events'.
-
- In most cases, the function `next-command-event' is more
- appropriate.
-
- - 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
- is filled in and returned, otherwise a new event object will be
- created.
-
- The event returned will be a keyboard, mouse press, or mouse
- release event. If there are non-command events available (mouse
- motion, sub-process output, etc) then these will be executed (with
- `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))
-
- Here is what happens if you call `next-command-event' and then
- press the right-arrow function key:
-
- (next-command-event)
- => #<keypress-event right>
-
- - Function: read-char
- This function reads and returns a character of command input. If a
- mouse click is detected, an error is signalled. The character
- typed is returned as an ASCII value. This function is retained for
- 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
- 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.
-
-\1f
-File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
-
-Dispatching an 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
- system (such as Expose events).
-
-\1f
-File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
-
-Quoted Character Input
-----------------------
-
- You can use the function `read-quoted-char' to ask the user to
-specify a character, and allow the user to specify a control or meta
-character conveniently, either literally or as an octal character code.
-The command `quoted-insert' uses this function.
-
- - 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
- returns the character represented by those digits in octal.
-
- Quitting is suppressed when the first character is read, so that
- the user can enter a `C-g'. *Note Quitting::.
-
- If PROMPT is supplied, it specifies a string for prompting the
- user. The prompt string is always displayed in the echo area,
- followed by a single `-'.
-
- In the following example, the user types in the octal number 177
- (which is 127 in decimal).
-
- (read-quoted-char "What character")
-
- ---------- Echo Area ----------
- What character-177
- ---------- Echo Area ----------
-
- => 127
-
-\1f
-File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
-
-Miscellaneous Event Input Features
-----------------------------------
-
- This section describes how to "peek ahead" at events without using
-them up, how to check for pending input, and how to discard pending
-input.
-
- See also the variables `last-command-event' and `last-command-char'
-(*Note Command Loop Info::).
-
- - Variable: unread-command-events
- This variable holds a list of events waiting to be read as command
- input. The events are used in the order they appear in the list,
- and removed one by one as they are used.
-
- The variable is needed because in some cases a function reads a
- event and then decides not to use it. Storing the event in this
- variable causes it to be processed normally, by the command loop
- or by the functions to read command input.
-
- 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 special meaning in a search, because these
- events should exit the search and then execute normally.
-
-
- - Variable: unread-command-event
- This variable holds a single event to be read as command input.
-
- This variable is mostly obsolete now that you can use
- `unread-command-events' instead; it exists only to support programs
- written for versions of XEmacs prior to 19.12.
-
- - Function: input-pending-p
- This function determines whether any command input is currently
- available to be read. It returns immediately, with value `t' if
- there is available input, `nil' otherwise. On rare occasions it
- may return `t' when no input is available.
-
- - Variable: last-input-event
- This variable is set to the last keyboard or mouse button event
- received.
-
- This variable is off limits: you may not set its value or modify
- the event that is its value, as it is destructively modified by
- `read-key-sequence'. If you want to keep a pointer to this value,
- you must use `copy-event'.
-
- Note that this variable is an alias for `last-input-char' in FSF
- Emacs.
-
- In the example below, a character is read (the character `1'). It
- becomes the value of `last-input-event', while `C-e' (from the
- `C-x C-e' command used to evaluate this expression) remains the
- value of `last-command-event'.
-
- (progn (print (next-command-event))
- (print last-command-event)
- last-input-event)
- -| #<keypress-event 1>
- -| #<keypress-event control-E>
- => #<keypress-event 1>
-
- - 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:
- 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
- set of characters.
-
- This function exists for compatibility with Emacs version 18.
-
- - Function: discard-input
- This function discards the contents of the terminal input buffer
- and cancels any keyboard macro that might be in the process of
- definition. It returns `nil'.
-
- In the following example, the user may type a number of characters
- right after starting the evaluation of the form. After the
- `sleep-for' finishes sleeping, `discard-input' discards any
- characters typed during the sleep.
-
- (progn (sleep-for 2)
- (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.
+ when you are sure that it is safe to do so.
projects / chise / xemacs-chise.git- / blobdiff