1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
58 After the command loop has translated a key sequence into a
59 definition, it invokes that definition using the function
60 `command-execute'. If the definition is a function that is a command,
61 `command-execute' calls `call-interactively', which reads the arguments
62 and calls the command. You can also call these functions yourself.
64 - Function: commandp object
65 Returns `t' if OBJECT is suitable for calling interactively; that
66 is, if OBJECT is a command. Otherwise, returns `nil'.
68 The interactively callable objects include strings and vectors
69 (treated as keyboard macros), lambda expressions that contain a
70 top-level call to `interactive', compiled-function objects made
71 from such lambda expressions, autoload objects that are declared
72 as interactive (non-`nil' fourth argument to `autoload'), and some
73 of the primitive functions.
75 A symbol is `commandp' if its function definition is `commandp'.
77 Keys and keymaps are not commands. Rather, they are used to look
78 up commands (*note Keymaps::).
80 See `documentation' in *Note Accessing Documentation::, for a
81 realistic example of using `commandp'.
83 - Function: call-interactively command &optional record-flag
84 This function calls the interactively callable function COMMAND,
85 reading arguments according to its interactive calling
86 specifications. An error is signaled if COMMAND is not a function
87 or if it cannot be called interactively (i.e., is not a command).
88 Note that keyboard macros (strings and vectors) are not accepted,
89 even though they are considered commands, because they are not
92 If RECORD-FLAG is the symbol `lambda', the interactive calling
93 arguments for `command' are read and returned as a list, but the
94 function is not called on them.
96 If RECORD-FLAG is `t', then this command and its arguments are
97 unconditionally added to the list `command-history'. Otherwise,
98 the command is added only if it uses the minibuffer to read an
99 argument. *Note Command History::.
101 - Function: command-execute command &optional record-flag
102 This function executes COMMAND as an editing command. The
103 argument COMMAND must satisfy the `commandp' predicate; i.e., it
104 must be an interactively callable function or a keyboard macro.
106 A string or vector as COMMAND is executed with
107 `execute-kbd-macro'. A function is passed to
108 `call-interactively', along with the optional RECORD-FLAG.
110 A symbol is handled by using its function definition in its place.
111 A symbol with an `autoload' definition counts as a command if it
112 was declared to stand for an interactively callable function.
113 Such a definition is handled by loading the specified library and
114 then rechecking the definition of the symbol.
116 - Command: execute-extended-command prefix-argument
117 This function reads a command name from the minibuffer using
118 `completing-read' (*note Completion::). Then it uses
119 `command-execute' to call the specified command. Whatever that
120 command returns becomes the value of `execute-extended-command'.
122 If the command asks for a prefix argument, it receives the value
123 PREFIX-ARGUMENT. If `execute-extended-command' is called
124 interactively, the current raw prefix argument is used for
125 PREFIX-ARGUMENT, and thus passed on to whatever command is run.
127 `execute-extended-command' is the normal definition of `M-x', so
128 it uses the string `M-x ' as a prompt. (It would be better to
129 take the prompt from the events used to invoke
130 `execute-extended-command', but that is painful to implement.) A
131 description of the value of the prefix argument, if any, also
132 becomes part of the prompt.
134 (execute-extended-command 1)
135 ---------- Buffer: Minibuffer ----------
136 1 M-x forward-word RET
137 ---------- Buffer: Minibuffer ----------
140 - Function: interactive-p
141 This function returns `t' if the containing function (the one that
142 called `interactive-p') was called interactively, with the function
143 `call-interactively'. (It makes no difference whether
144 `call-interactively' was called from Lisp or directly from the
145 editor command loop.) If the containing function was called by
146 Lisp evaluation (or with `apply' or `funcall'), then it was not
147 called interactively.
149 The most common use of `interactive-p' is for deciding whether to
150 print an informative message. As a special exception,
151 `interactive-p' returns `nil' whenever a keyboard macro is being
152 run. This is to suppress the informative messages and speed
153 execution of the macro.
165 (setq foobar (list (foo) (interactive-p))))
172 ;; This does not print anything.
178 File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
180 Information from the Command Loop
181 =================================
183 The editor command loop sets several Lisp variables to keep status
184 records for itself and for commands that are run.
186 - Variable: last-command
187 This variable records the name of the previous command executed by
188 the command loop (the one before the current command). Normally
189 the value is a symbol with a function definition, but this is not
192 The value is copied from `this-command' when a command returns to
193 the command loop, except when the command specifies a prefix
194 argument for the following command.
196 - Variable: this-command
197 This variable records the name of the command now being executed by
198 the editor command loop. Like `last-command', it is normally a
199 symbol with a function definition.
201 The command loop sets this variable just before running a command,
202 and copies its value into `last-command' when the command finishes
203 (unless the command specifies a prefix argument for the following
206 Some commands set this variable during their execution, as a flag
207 for whatever command runs next. In particular, the functions for
208 killing text set `this-command' to `kill-region' so that any kill
209 commands immediately following will know to append the killed text
210 to the previous kill.
212 If you do not want a particular command to be recognized as the
213 previous command in the case where it got an error, you must code that
214 command to prevent this. One way is to set `this-command' to `t' at the
215 beginning of the command, and set `this-command' back to its proper
216 value at the end, like this:
220 (let ((old-this-command this-command))
221 (setq this-command t)
223 (setq this-command old-this-command)))
225 - Function: this-command-keys
226 This function returns a vector containing the key and mouse events
227 that invoked the present command, plus any previous commands that
228 generated the prefix argument for this command. (Note: this is not
229 the same as in FSF Emacs, which can return a string.) *Note
232 This function copies the vector and the events; it is safe to keep
236 ;; Now use `C-u C-x C-e' to evaluate that.
237 => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
239 - Variable: last-command-event
240 This variable is set to the last input event that was read by the
241 command loop as part of a command. The principal use of this
242 variable is in `self-insert-command', which uses it to decide which
245 This variable is off limits: you may not set its value or modify
246 the event that is its value, as it is destructively modified by
247 `read-key-sequence'. If you want to keep a pointer to this value,
248 you must use `copy-event'.
250 Note that this variable is an alias for `last-command-char' in FSF
254 ;; Now type `C-u C-x C-e'.
255 => #<keypress-event control-E>
257 - Variable: last-command-char
258 If the value of `last-command-event' is a keyboard event, then this
259 is the nearest character equivalent to it (or `nil' if there is no
260 character equivalent). `last-command-char' is the character that
261 `self-insert-command' will insert in the buffer. Remember that
262 there is _not_ a one-to-one mapping between keyboard events and
263 XEmacs characters: many keyboard events have no corresponding
264 character, and when the Mule feature is available, most characters
265 can not be input on standard keyboards, except possibly with help
266 from an input method. So writing code that examines this variable
267 to determine what key has been typed is bad practice, unless you
268 are certain that it will be one of a small set of characters.
270 This variable exists for compatibility with Emacs version 18.
273 ;; Now use `C-u C-x C-e' to evaluate that.
277 - Variable: current-mouse-event
278 This variable holds the mouse-button event which invoked this
279 command, or `nil'. This is what `(interactive "e")' returns.
281 - Variable: echo-keystrokes
282 This variable determines how much time should elapse before command
283 characters echo. Its value must be an integer, which specifies the
284 number of seconds to wait before echoing. If the user types a
285 prefix key (say `C-x') and then delays this many seconds before
286 continuing, the key `C-x' is echoed in the echo area. Any
287 subsequent characters in the same command will be echoed as well.
289 If the value is zero, then command input is not echoed.
292 File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
297 The XEmacs command loop reads a sequence of "events" that represent
298 keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs,
299 events are a primitive Lisp type that must be manipulated using their
300 own accessor and settor primitives. This section describes the
301 representation and meaning of input events in detail.
303 A key sequence that starts with a mouse event is read using the
304 keymaps of the buffer in the window that the mouse was in, not the
305 current buffer. This does not imply that clicking in a window selects
306 that window or its buffer--that is entirely under the control of the
307 command binding of the key sequence.
309 For information about how exactly the XEmacs command loop works,
310 *Note Reading Input::.
312 - Function: eventp object
313 This function returns non-`nil' if EVENT is an input event.
317 * Event Types:: Events come in different types.
318 * Event Contents:: What the contents of each event type are.
319 * Event Predicates:: Querying whether an event is of a
321 * Accessing Mouse Event Positions::
322 Determining where a mouse event occurred,
324 * Accessing Other Event Info:: Accessing non-positional event info.
325 * Working With Events:: Creating, copying, and destroying events.
326 * Converting Events:: Converting between events, keys, and
330 File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events
335 Events represent keyboard or mouse activity or status changes of
336 various sorts, such as process input being available or a timeout being
337 triggered. The different event types are as follows:
340 A key was pressed. Note that modifier keys such as "control",
341 "shift", and "alt" do not generate events; instead, they are
342 tracked internally by XEmacs, and non-modifier key presses
343 generate events that specify both the key pressed and the
344 modifiers that were held down at the time.
348 A button was pressed or released. Along with the button that was
349 pressed or released, button events specify the modifier keys that
350 were held down at the time and the position of the pointer at the
354 The pointer was moved. Along with the position of the pointer,
355 these events also specify the modifier keys that were held down at
359 A menu item was selected, the scrollbar was used, or a drag or a
363 Input is available on a process.
366 A timeout has triggered.
369 Some window-system-specific action (such as a frame being resized
370 or a portion of a frame needing to be redrawn) has occurred. The
371 contents of this event are not accessible at the E-Lisp level, but
372 `dispatch-event' knows what to do with an event of this type.
375 This is a special kind of event specifying that a particular
376 function needs to be called when this event is dispatched. An
377 event of this type is sometimes placed in the event queue when a
378 magic event is processed. This kind of event should generally
379 just be passed off to `dispatch-event'. *Note Dispatching an
383 File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events
385 Contents of the Different Types of Events
386 -----------------------------------------
388 Every event, no matter what type it is, contains a timestamp (which
389 is typically an offset in milliseconds from when the X server was
390 started) indicating when the event occurred. In addition, many events
391 contain a "channel", which specifies which frame the event occurred on,
392 and/or a value indicating which modifier keys (shift, control, etc.)
393 were held down at the time of the event.
395 The contents of each event are as follows:
404 Which key was pressed. This is an integer (in the printing
405 ASCII range: >32 and <127) or a symbol such as `left' or
406 `right'. Note that many physical keys are actually treated
407 as two separate keys, depending on whether the shift key is
408 pressed; for example, the "a" key is treated as either "a" or
409 "A" depending on the state of the shift key, and the "1" key
410 is similarly treated as either "1" or "!" on most keyboards.
411 In such cases, the shift key does not show up in the modifier
412 list. For other keys, such as `backspace', the shift key
413 shows up as a regular modifier.
416 Which modifier keys were pressed. As mentioned above, the
417 shift key is not treated as a modifier for many keys and will
418 not show up in this list in such cases.
428 What button went down or up. Buttons are numbered starting
432 Which modifier keys were pressed. The special business
433 mentioned above for the shift key does _not_ apply to mouse
438 The position of the pointer (in pixels) at the time of the
449 The position of the pointer (in pixels) after it moved.
452 Which modifier keys were pressed. The special business
453 mentioned above for the shift key does _not_ apply to mouse
461 The E-Lisp function to call for this event. This is normally
462 either `eval' or `call-interactively'.
465 The object to pass to the function. This is normally the
466 callback that was specified in the menu description.
469 What button went down or up. Buttons are numbered starting
473 Which modifier keys were pressed. The special business
474 mentioned above for the shift key does _not_ apply to mouse
479 The position of the pointer (in pixels) at the time of the
487 The Emacs "process" object in question.
494 The E-Lisp function to call for this timeout. It is called
495 with one argument, the event.
498 Some Lisp object associated with this timeout, to make it
499 easier to tell them apart. The function and object for this
500 event were specified when the timeout was set.
505 (The rest of the information in this event is not user-accessible.)
512 An E-Lisp function to call when this event is dispatched.
515 The object to pass to the function. The function and object
516 are set when the event is created.
518 - Function: event-type event
519 Return the type of EVENT.
521 This will be a symbol; one of
527 A mouse button was pressed.
530 A mouse button was released.
536 Some other user action happened; typically, this is a menu
537 selection, scrollbar action, or drag and drop action.
540 Input is available from a subprocess.
543 A timeout has expired.
546 This causes a specified action to occur when dispatched.
549 Some window-system-specific event has occurred.
552 File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events
557 The following predicates return whether an object is an event of a
560 - Function: key-press-event-p object
561 This is true if OBJECT is a key-press event.
563 - Function: button-event-p object object
564 This is true if OBJECT is a mouse button-press or button-release
567 - Function: button-press-event-p object
568 This is true if OBJECT is a mouse button-press event.
570 - Function: button-release-event-p object
571 This is true if OBJECT is a mouse button-release event.
573 - Function: motion-event-p object
574 This is true if OBJECT is a mouse motion event.
576 - Function: mouse-event-p object
577 This is true if OBJECT is a mouse button-press, button-release or
580 - Function: eval-event-p object
581 This is true if OBJECT is an eval event.
583 - Function: misc-user-event-p object
584 This is true if OBJECT is a misc-user event.
586 - Function: process-event-p object
587 This is true if OBJECT is a process event.
589 - Function: timeout-event-p object
590 This is true if OBJECT is a timeout event.
592 - Function: event-live-p object
593 This is true if OBJECT is any event that has not been deallocated.
596 File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events
598 Accessing the Position of a Mouse Event
599 ---------------------------------------
601 Unlike other events, mouse events (i.e. motion, button-press,
602 button-release, and drag or drop type misc-user events) occur in a
603 particular location on the screen. Many primitives are provided for
604 determining exactly where the event occurred and what is under that
609 * Frame-Level Event Position Info::
610 * Window-Level Event Position Info::
611 * Event Text Position Info::
612 * Event Glyph Position Info::
613 * Event Toolbar Position Info::
614 * Other Event Position Info::
617 File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
619 Frame-Level Event Position Info
620 ...............................
622 The following functions return frame-level information about where a
623 mouse event occurred.
625 - Function: event-frame event
626 This function returns the "channel" or frame that the given mouse
627 motion, button press, button release, or misc-user event occurred
628 in. This will be `nil' for non-mouse events.
630 - Function: event-x-pixel event
631 This function returns the X position in pixels of the given mouse
632 event. The value returned is relative to the frame the event
633 occurred in. This will signal an error if the event is not a
636 - Function: event-y-pixel event
637 This function returns the Y position in pixels of the given mouse
638 event. The value returned is relative to the frame the event
639 occurred in. This will signal an error if the event is not a
643 File: lispref.info, Node: Window-Level Event Position Info, Next: Event Text Position Info, Prev: Frame-Level Event Position Info, Up: Accessing Mouse Event Positions
645 Window-Level Event Position Info
646 ................................
648 The following functions return window-level information about where
649 a mouse event occurred.
651 - Function: event-window event
652 Given a mouse motion, button press, button release, or misc-user
653 event, compute and return the window on which that event occurred.
654 This may be `nil' if the event occurred in the border or over a
655 toolbar. The modeline is considered to be within the window it
658 - Function: event-buffer event
659 Given a mouse motion, button press, button release, or misc-user
660 event, compute and return the buffer of the window on which that
661 event occurred. This may be `nil' if the event occurred in the
662 border or over a toolbar. The modeline is considered to be within
663 the window it describes. This is equivalent to calling
664 `event-window' and then calling `window-buffer' on the result if
667 - Function: event-window-x-pixel event
668 This function returns the X position in pixels of the given mouse
669 event. The value returned is relative to the window the event
670 occurred in. This will signal an error if the event is not a
671 mouse-motion, button-press, button-release, or misc-user event.
673 - Function: event-window-y-pixel event
674 This function returns the Y position in pixels of the given mouse
675 event. The value returned is relative to the window the event
676 occurred in. This will signal an error if the event is not a
677 mouse-motion, button-press, button-release, or misc-user event.
680 File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
682 Event Text Position Info
683 ........................
685 The following functions return information about the text (including
686 the modeline) that a mouse event occurred over or near.
688 - Function: event-over-text-area-p event
689 Given a mouse-motion, button-press, button-release, or misc-user
690 event, this function returns `t' if the event is over the text
691 area of a window. Otherwise, `nil' is returned. The modeline is
692 not considered to be part of the text area.
694 - Function: event-over-modeline-p event
695 Given a mouse-motion, button-press, button-release, or misc-user
696 event, this function returns `t' if the event is over the modeline
697 of a window. Otherwise, `nil' is returned.
699 - Function: event-x event
700 This function returns the X position of the given mouse-motion,
701 button-press, button-release, or misc-user event in characters.
702 This is relative to the window the event occurred over.
704 - Function: event-y event
705 This function returns the Y position of the given mouse-motion,
706 button-press, button-release, or misc-user event in characters.
707 This is relative to the window the event occurred over.
709 - Function: event-point event
710 This function returns the character position of the given
711 mouse-motion, button-press, button-release, or misc-user event.
712 If the event did not occur over a window, or did not occur over
713 text, then this returns `nil'. Otherwise, it returns an index
714 into the buffer visible in the event's window.
716 - Function: event-closest-point event
717 This function returns the character position of the given
718 mouse-motion, button-press, button-release, or misc-user event.
719 If the event did not occur over a window or over text, it returns
720 the closest point to the location of the event. If the Y pixel
721 position overlaps a window and the X pixel position is to the left
722 of that window, the closest point is the beginning of the line
723 containing the Y position. If the Y pixel position overlaps a
724 window and the X pixel position is to the right of that window,
725 the closest point is the end of the line containing the Y
726 position. If the Y pixel position is above a window, 0 is
727 returned. If it is below a window, the value of `(window-end)' is
731 File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions
733 Event Glyph Position Info
734 .........................
736 The following functions return information about the glyph (if any)
737 that a mouse event occurred over.
739 - Function: event-over-glyph-p event
740 Given a mouse-motion, button-press, button-release, or misc-user
741 event, this function returns `t' if the event is over a glyph.
742 Otherwise, `nil' is returned.
744 - Function: event-glyph-extent event
745 If the given mouse-motion, button-press, button-release, or
746 misc-user event happened on top of a glyph, this returns its
747 extent; else `nil' is returned.
749 - Function: event-glyph-x-pixel event
750 Given a mouse-motion, button-press, button-release, or misc-user
751 event over a glyph, this function returns the X position of the
752 pointer relative to the upper left of the glyph. If the event is
753 not over a glyph, it returns `nil'.
755 - Function: event-glyph-y-pixel event
756 Given a mouse-motion, button-press, button-release, or misc-user
757 event over a glyph, this function returns the Y position of the
758 pointer relative to the upper left of the glyph. If the event is
759 not over a glyph, it returns `nil'.
762 File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions
764 Event Toolbar Position Info
765 ...........................
767 - Function: event-over-toolbar-p event
768 Given a mouse-motion, button-press, button-release, or misc-user
769 event, this function returns `t' if the event is over a toolbar.
770 Otherwise, `nil' is returned.
772 - Function: event-toolbar-button event
773 If the given mouse-motion, button-press, button-release, or
774 misc-user event happened on top of a toolbar button, this function
775 returns the button. Otherwise, `nil' is returned.
778 File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions
780 Other Event Position Info
781 .........................
783 - Function: event-over-border-p event
784 Given a mouse-motion, button-press, button-release, or misc-user
785 event, this function returns `t' if the event is over an internal
786 toolbar. Otherwise, `nil' is returned.
789 File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events
791 Accessing the Other Contents of Events
792 --------------------------------------
794 The following functions allow access to the contents of events other
795 than the position info described in the previous section.
797 - Function: event-timestamp event
798 This function returns the timestamp of the given event object.
800 - Function: event-device event
801 This function returns the device that the given event occurred on.
803 - Function: event-key event
804 This function returns the Keysym of the given key-press event.
805 This will be the ASCII code of a printing character, or a symbol.
807 - Function: event-button event
808 This function returns the button-number of the given button-press
809 or button-release event.
811 - Function: event-modifiers event
812 This function returns a list of symbols, the names of the modifier
813 keys which were down when the given mouse or keyboard event was
816 - Function: event-modifier-bits event
817 This function returns a number representing the modifier keys
818 which were down when the given mouse or keyboard event was
821 - Function: event-function event
822 This function returns the callback function of the given timeout,
823 misc-user, or eval event.
825 - Function: event-object event
826 This function returns the callback function argument of the given
827 timeout, misc-user, or eval event.
829 - Function: event-process event
830 This function returns the process of the given process event.
833 File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events
838 XEmacs provides primitives for creating, copying, and destroying
839 event objects. Many functions that return events take an event object
840 as an argument and fill in the fields of this event; or they make accept
841 either an event object or `nil', creating the event object first in the
844 - Function: make-event &optional type plist
845 This function creates a new event structure. If no arguments are
846 specified, the created event will be empty. To specify the event
847 type, use the TYPE argument. The allowed types are `empty',
848 `key-press', `button-press', `button-release', `motion', or
851 PLIST is a property list, the properties being compatible to those
852 returned by `event-properties'. For events other than `empty', it
853 is mandatory to specify certain properties. For `empty' events,
854 PLIST must be `nil'. The list is "canonicalized", which means
855 that if a property keyword is present more than once, only the
856 first instance is taken into account. Specifying an unknown or
857 illegal property signals an error.
859 The following properties are allowed:
862 The event channel. This is a frame or a console. For mouse
863 events (of type `button-press', `button-release' and
864 `motion'), this must be a frame. For key-press events, it
865 must be a console. If channel is unspecified by PLIST, it
866 will be set to the selected frame or selected console, as
870 The event key. This is either a symbol or a character. It
871 is allowed (and required) only for key-press events.
874 The event button. This an integer, either 1, 2 or 3. It is
875 allowed only for button-press and button-release events.
878 The event modifiers. This is a list of modifier symbols. It
879 is allowed for key-press, button-press, button-release and
883 The event X coordinate. This is an integer. It is relative
884 to the channel's root window, and is allowed for
885 button-press, button-release and motion events.
888 The event Y coordinate. This is an integer. It is relative
889 to the channel's root window, and is allowed for
890 button-press, button-release and motion events. This means
891 that, for instance, to access the toolbar, the `y' property
892 will have to be negative.
895 The event timestamp, a non-negative integer. Allowed for all
898 _WARNING_: the event object returned by this function may be a
899 reused one; see the function `deallocate-event'.
901 The events created by `make-event' can be used as non-interactive
902 arguments to the functions with an `(interactive "e")'
905 Here are some basic examples of usage:
907 ;; Create an empty event.
911 ;; Try creating a key-press event.
912 (make-event 'key-press)
913 error--> Undefined key for keypress event
915 ;; Creating a key-press event, try 2
916 (make-event 'key-press '(key home))
917 => #<keypress-event home>
919 ;; Create a key-press event of dubious fame.
920 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
921 => #<keypress-event control-meta-alt-shift-escape>
923 ;; Create a M-button1 event at coordinates defined by variables
925 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
926 => #<buttondown-event meta-button1>
928 ;; Create a similar button-release event.
929 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
930 => #<buttonup-event meta-button1up>
932 ;; Create a mouse-motion event.
933 (make-event 'motion '(x 20 y 30))
934 => #<motion-event 20, 30>
936 (event-properties (make-event 'motion '(x 20 y 30)))
937 => (channel #<x-frame "emacs" 0x8e2> x 20 y 30
938 modifiers nil timestamp 0)
940 In conjunction with `event-properties', you can use `make-event'
941 to create modified copies of existing events. For instance, the
942 following code will return an `equal' copy of EVENT:
944 (make-event (event-type EVENT)
945 (event-properties EVENT))
947 Note, however, that you cannot use `make-event' as the generic
948 replacement for `copy-event', because it does not allow creating
949 all of the event types.
951 To create a modified copy of an event, you can use the
952 canonicalization feature of PLIST. The following example creates
953 a copy of EVENT, but with `modifiers' reset to `nil'.
955 (make-event (event-type EVENT)
956 (append '(modifiers nil)
957 (event-properties EVENT)))
959 - Function: copy-event event1 &optional event2
960 This function makes a copy of the given event object. If a second
961 argument is given, the first event is copied into the second and
962 the second is returned. If the second argument is not supplied
963 (or is `nil') then a new event will be made.
965 - Function: deallocate-event event
966 This function allows the given event structure to be reused. You
967 *MUST NOT* use this event object after calling this function with
968 it. You will lose. It is not necessary to call this function, as
969 event objects are garbage-collected like all other objects;
970 however, it may be more efficient to explicitly deallocate events
971 when you are sure that that is safe.
974 File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
979 XEmacs provides some auxiliary functions for converting between
980 events and other ways of representing keys. These are useful when
981 working with ASCII strings and with keymaps.
983 - Function: character-to-event ch &optional event device
984 This function converts a numeric ASCII value to an event structure,
985 replete with modifier bits. CH is the character to convert, and
986 EVENT is the event object to fill in. This function contains
987 knowledge about what the codes "mean"--for example, the number 9 is
988 converted to the character <Tab>, not the distinct character
991 Note that CH does not have to be a numeric value, but can be a
992 symbol such as `clear' or a list such as `(control backspace)'.
994 If `event' is not `nil', it is modified; otherwise, a new event
995 object is created. In both cases, the event is returned.
997 Optional third arg DEVICE is the device to store in the event;
998 this also affects whether the high bit is interpreted as a meta
999 key. A value of `nil' means use the selected device but always
1000 treat the high bit as meta.
1002 Beware that `character-to-event' and `event-to-character' are not
1003 strictly inverse functions, since events contain much more
1004 information than the ASCII character set can encode.
1006 - Function: event-to-character event &optional allow-extra-modifiers
1007 allow-meta allow-non-ascii
1008 This function returns the closest ASCII approximation to EVENT.
1009 If the event isn't a keypress, this returns `nil'.
1011 If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
1012 translation; it will ignore modifier keys other than <control> and
1013 <meta>, and will ignore the <shift> modifier on those characters
1014 which have no shifted ASCII equivalent (<Control-Shift-A> for
1015 example, will be mapped to the same ASCII code as <Control-A>).
1017 If ALLOW-META is non-`nil', then the <Meta> modifier will be
1018 represented by turning on the high bit of the byte returned;
1019 otherwise, `nil' will be returned for events containing the <Meta>
1022 If ALLOW-NON-ASCII is non-`nil', then characters which are present
1023 in the prevailing character set (*note variable
1024 `character-set-property': Keymaps.) will be returned as their code
1025 in that character set, instead of the return value being
1026 restricted to ASCII.
1028 Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
1029 ambiguous, as both use the high bit; <M-x> and <oslash> will be
1032 - Function: events-to-keys events &optional no-mice
1033 Given a vector of event objects, this function returns a vector of
1034 key descriptors, or a string (if they all fit in the ASCII range).
1035 Optional arg NO-MICE means that button events are not allowed.
1038 File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
1043 The editor command loop reads keyboard input using the function
1044 `next-event' and constructs key sequences out of the events using
1045 `dispatch-event'. Lisp programs can also use the function
1046 `read-key-sequence', which reads input a key sequence at a time. See
1047 also `momentary-string-display' in *Note Temporary Displays::, and
1048 `sit-for' in *Note Waiting::. *Note Terminal Input::, for functions
1049 and variables for controlling terminal input modes and debugging
1052 For higher-level input facilities, see *Note Minibuffers::.
1056 * Key Sequence Input:: How to read one key sequence.
1057 * Reading One Event:: How to read just one event.
1058 * Dispatching an Event:: What to do with an event once it has been read.
1059 * Quoted Character Input:: Asking the user to specify a character.
1060 * Peeking and Discarding:: How to reread or throw away input events.
1063 File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
1068 Lisp programs can read input a key sequence at a time by calling
1069 `read-key-sequence'; for example, `describe-key' uses it to read the
1072 - Function: read-key-sequence prompt
1073 This function reads a sequence of keystrokes or mouse clicks and
1074 returns it as a vector of events. It keeps reading events until
1075 it has accumulated a full key sequence; that is, enough to specify
1076 a non-prefix command using the currently active keymaps.
1078 The vector and the event objects it contains are freshly created,
1079 and will not be side-effected by subsequent calls to this function.
1081 The function `read-key-sequence' suppresses quitting: `C-g' typed
1082 while reading with this function works like any other character,
1083 and does not set `quit-flag'. *Note Quitting::.
1085 The argument PROMPT is either a string to be displayed in the echo
1086 area as a prompt, or `nil', meaning not to display a prompt.
1088 If the user selects a menu item while we are prompting for a key
1089 sequence, the returned value will be a vector of a single
1090 menu-selection event (a misc-user event). An error will be
1091 signalled if you pass this value to `lookup-key' or a related
1094 In the example below, the prompt `?' is displayed in the echo area,
1095 and the user types `C-x C-f'.
1097 (read-key-sequence "?")
1099 ---------- Echo Area ----------
1101 ---------- Echo Area ----------
1103 => [#<keypress-event control-X> #<keypress-event control-F>]
1105 If an input character is an upper-case letter and has no key binding,
1106 but its lower-case equivalent has one, then `read-key-sequence'
1107 converts the character to lower case. Note that `lookup-key' does not
1108 perform case conversion in this way.
1111 File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
1116 The lowest level functions for command input are those which read a
1117 single event. These functions often make a distinction between
1118 "command events", which are user actions (keystrokes and mouse
1119 actions), and other events, which serve as communication between XEmacs
1120 and the window system.
1122 - Function: next-event &optional event prompt
1123 This function reads and returns the next available event from the
1124 window system or terminal driver, waiting if necessary until an
1125 event is available. Pass this object to `dispatch-event' to
1126 handle it. If an event object is supplied, it is filled in and
1127 returned; otherwise a new event object will be created.
1129 Events can come directly from the user, from a keyboard macro, or
1130 from `unread-command-events'.
1132 In most cases, the function `next-command-event' is more
1135 - Function: next-command-event &optional event
1136 This function returns the next available "user" event from the
1137 window system or terminal driver. Pass this object to
1138 `dispatch-event' to handle it. If an event object is supplied, it
1139 is filled in and returned, otherwise a new event object will be
1142 The event returned will be a keyboard, mouse press, or mouse
1143 release event. If there are non-command events available (mouse
1144 motion, sub-process output, etc) then these will be executed (with
1145 `dispatch-event') and discarded. This function is provided as a
1146 convenience; it is equivalent to the Lisp code
1150 (not (or (key-press-event-p event)
1151 (button-press-event-p event)
1152 (button-release-event-p event)
1153 (menu-event-p event))))
1154 (dispatch-event event))
1156 Here is what happens if you call `next-command-event' and then
1157 press the right-arrow function key:
1159 (next-command-event)
1160 => #<keypress-event right>
1162 - Function: read-char
1163 This function reads and returns a character of command input. If a
1164 mouse click is detected, an error is signalled. The character
1165 typed is returned as an ASCII value. This function is retained for
1166 compatibility with Emacs 18, and is most likely the wrong thing
1167 for you to be using: consider using `next-command-event' instead.
1169 - Function: enqueue-eval-event function object
1170 This function adds an eval event to the back of the queue. The
1171 eval event will be the next event read after all pending events.
1174 File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
1176 Dispatching an Event
1177 --------------------
1179 - Function: dispatch-event event
1180 Given an event object returned by `next-event', this function
1181 executes it. This is the basic function that makes XEmacs respond
1182 to user input; it also deals with notifications from the window
1183 system (such as Expose events).
1186 File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
1188 Quoted Character Input
1189 ----------------------
1191 You can use the function `read-quoted-char' to ask the user to
1192 specify a character, and allow the user to specify a control or meta
1193 character conveniently, either literally or as an octal character code.
1194 The command `quoted-insert' uses this function.
1196 - Function: read-quoted-char &optional prompt
1197 This function is like `read-char', except that if the first
1198 character read is an octal digit (0-7), it reads up to two more
1199 octal digits (but stopping if a non-octal digit is found) and
1200 returns the character represented by those digits in octal.
1202 Quitting is suppressed when the first character is read, so that
1203 the user can enter a `C-g'. *Note Quitting::.
1205 If PROMPT is supplied, it specifies a string for prompting the
1206 user. The prompt string is always displayed in the echo area,
1207 followed by a single `-'.
1209 In the following example, the user types in the octal number 177
1210 (which is 127 in decimal).
1212 (read-quoted-char "What character")
1214 ---------- Echo Area ----------
1216 ---------- Echo Area ----------
1221 File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
1223 Miscellaneous Event Input Features
1224 ----------------------------------
1226 This section describes how to "peek ahead" at events without using
1227 them up, how to check for pending input, and how to discard pending
1230 See also the variables `last-command-event' and `last-command-char'
1231 (*Note Command Loop Info::).
1233 - Variable: unread-command-events
1234 This variable holds a list of events waiting to be read as command
1235 input. The events are used in the order they appear in the list,
1236 and removed one by one as they are used.
1238 The variable is needed because in some cases a function reads a
1239 event and then decides not to use it. Storing the event in this
1240 variable causes it to be processed normally, by the command loop
1241 or by the functions to read command input.
1243 For example, the function that implements numeric prefix arguments
1244 reads any number of digits. When it finds a non-digit event, it
1245 must unread the event so that it can be read normally by the
1246 command loop. Likewise, incremental search uses this feature to
1247 unread events with no special meaning in a search, because these
1248 events should exit the search and then execute normally.
1251 - Variable: unread-command-event
1252 This variable holds a single event to be read as command input.
1254 This variable is mostly obsolete now that you can use
1255 `unread-command-events' instead; it exists only to support programs
1256 written for versions of XEmacs prior to 19.12.
1258 - Function: input-pending-p
1259 This function determines whether any command input is currently
1260 available to be read. It returns immediately, with value `t' if
1261 there is available input, `nil' otherwise. On rare occasions it
1262 may return `t' when no input is available.
1264 - Variable: last-input-event
1265 This variable is set to the last keyboard or mouse button event
1268 This variable is off limits: you may not set its value or modify
1269 the event that is its value, as it is destructively modified by
1270 `read-key-sequence'. If you want to keep a pointer to this value,
1271 you must use `copy-event'.
1273 Note that this variable is an alias for `last-input-char' in FSF
1276 In the example below, a character is read (the character `1'). It
1277 becomes the value of `last-input-event', while `C-e' (from the
1278 `C-x C-e' command used to evaluate this expression) remains the
1279 value of `last-command-event'.
1281 (progn (print (next-command-event))
1282 (print last-command-event)
1284 -| #<keypress-event 1>
1285 -| #<keypress-event control-E>
1286 => #<keypress-event 1>
1288 - Variable: last-input-char
1289 If the value of `last-input-event' is a keyboard event, then this
1290 is the nearest ASCII equivalent to it. Remember that there is
1291 _not_ a 1:1 mapping between keyboard events and ASCII characters:
1292 the set of keyboard events is much larger, so writing code that
1293 examines this variable to determine what key has been typed is bad
1294 practice, unless you are certain that it will be one of a small
1297 This function exists for compatibility with Emacs version 18.
1299 - Function: discard-input
1300 This function discards the contents of the terminal input buffer
1301 and cancels any keyboard macro that might be in the process of
1302 definition. It returns `nil'.
1304 In the following example, the user may type a number of characters
1305 right after starting the evaluation of the form. After the
1306 `sleep-for' finishes sleeping, `discard-input' discards any
1307 characters typed during the sleep.
1309 (progn (sleep-for 2)