1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
55 Information from the Command Loop
56 =================================
58 The editor command loop sets several Lisp variables to keep status
59 records for itself and for commands that are run.
61 - Variable: last-command
62 This variable records the name of the previous command executed by
63 the command loop (the one before the current command). Normally
64 the value is a symbol with a function definition, but this is not
67 The value is copied from `this-command' when a command returns to
68 the command loop, except when the command specifies a prefix
69 argument for the following command.
71 - Variable: this-command
72 This variable records the name of the command now being executed by
73 the editor command loop. Like `last-command', it is normally a
74 symbol with a function definition.
76 The command loop sets this variable just before running a command,
77 and copies its value into `last-command' when the command finishes
78 (unless the command specifies a prefix argument for the following
81 Some commands set this variable during their execution, as a flag
82 for whatever command runs next. In particular, the functions for
83 killing text set `this-command' to `kill-region' so that any kill
84 commands immediately following will know to append the killed text
87 If you do not want a particular command to be recognized as the
88 previous command in the case where it got an error, you must code that
89 command to prevent this. One way is to set `this-command' to `t' at the
90 beginning of the command, and set `this-command' back to its proper
91 value at the end, like this:
95 (let ((old-this-command this-command))
98 (setq this-command old-this-command)))
100 - Function: this-command-keys
101 This function returns a vector containing the key and mouse events
102 that invoked the present command, plus any previous commands that
103 generated the prefix argument for this command. (Note: this is not
104 the same as in FSF Emacs, which can return a string.) *Note
107 This function copies the vector and the events; it is safe to keep
111 ;; Now use `C-u C-x C-e' to evaluate that.
112 => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
114 - Variable: last-command-event
115 This variable is set to the last input event that was read by the
116 command loop as part of a command. The principal use of this
117 variable is in `self-insert-command', which uses it to decide which
120 This variable is off limits: you may not set its value or modify
121 the event that is its value, as it is destructively modified by
122 `read-key-sequence'. If you want to keep a pointer to this value,
123 you must use `copy-event'.
125 Note that this variable is an alias for `last-command-char' in FSF
129 ;; Now type `C-u C-x C-e'.
130 => #<keypress-event control-E>
132 - Variable: last-command-char
133 If the value of `last-command-event' is a keyboard event, then this
134 is the nearest character equivalent to it (or `nil' if there is no
135 character equivalent). `last-command-char' is the character that
136 `self-insert-command' will insert in the buffer. Remember that
137 there is *not* a one-to-one mapping between keyboard events and
138 XEmacs characters: many keyboard events have no corresponding
139 character, and when the Mule feature is available, most characters
140 can not be input on standard keyboards, except possibly with help
141 from an input method. So writing code that examines this variable
142 to determine what key has been typed is bad practice, unless you
143 are certain that it will be one of a small set of characters.
145 This variable exists for compatibility with Emacs version 18.
148 ;; Now use `C-u C-x C-e' to evaluate that.
152 - Variable: current-mouse-event
153 This variable holds the mouse-button event which invoked this
154 command, or `nil'. This is what `(interactive "e")' returns.
156 - Variable: echo-keystrokes
157 This variable determines how much time should elapse before command
158 characters echo. Its value must be an integer, which specifies the
159 number of seconds to wait before echoing. If the user types a
160 prefix key (say `C-x') and then delays this many seconds before
161 continuing, the key `C-x' is echoed in the echo area. Any
162 subsequent characters in the same command will be echoed as well.
164 If the value is zero, then command input is not echoed.
167 File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
172 The XEmacs command loop reads a sequence of "events" that represent
173 keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs,
174 events are a primitive Lisp type that must be manipulated using their
175 own accessor and settor primitives. This section describes the
176 representation and meaning of input events in detail.
178 A key sequence that starts with a mouse event is read using the
179 keymaps of the buffer in the window that the mouse was in, not the
180 current buffer. This does not imply that clicking in a window selects
181 that window or its buffer--that is entirely under the control of the
182 command binding of the key sequence.
184 For information about how exactly the XEmacs command loop works,
185 *Note Reading Input::.
187 - Function: eventp OBJECT
188 This function returns non-`nil' if EVENT is an input event.
192 * Event Types:: Events come in different types.
193 * Event Contents:: What the contents of each event type are.
194 * Event Predicates:: Querying whether an event is of a
196 * Accessing Mouse Event Positions::
197 Determining where a mouse event occurred,
199 * Accessing Other Event Info:: Accessing non-positional event info.
200 * Working With Events:: Creating, copying, and destroying events.
201 * Converting Events:: Converting between events, keys, and
205 File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events
210 Events represent keyboard or mouse activity or status changes of
211 various sorts, such as process input being available or a timeout being
212 triggered. The different event types are as follows:
215 A key was pressed. Note that modifier keys such as "control",
216 "shift", and "alt" do not generate events; instead, they are
217 tracked internally by XEmacs, and non-modifier key presses
218 generate events that specify both the key pressed and the
219 modifiers that were held down at the time.
223 A button was pressed or released. Along with the button that was
224 pressed or released, button events specify the modifier keys that
225 were held down at the time and the position of the pointer at the
229 The pointer was moved. Along with the position of the pointer,
230 these events also specify the modifier keys that were held down at
234 A menu item was selected, the scrollbar was used, or a drag or a
238 Input is available on a process.
241 A timeout has triggered.
244 Some window-system-specific action (such as a frame being resized
245 or a portion of a frame needing to be redrawn) has occurred. The
246 contents of this event are not accessible at the E-Lisp level, but
247 `dispatch-event' knows what to do with an event of this type.
250 This is a special kind of event specifying that a particular
251 function needs to be called when this event is dispatched. An
252 event of this type is sometimes placed in the event queue when a
253 magic event is processed. This kind of event should generally
254 just be passed off to `dispatch-event'. *Note Dispatching an
258 File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events
260 Contents of the Different Types of Events
261 -----------------------------------------
263 Every event, no matter what type it is, contains a timestamp (which
264 is typically an offset in milliseconds from when the X server was
265 started) indicating when the event occurred. In addition, many events
266 contain a "channel", which specifies which frame the event occurred on,
267 and/or a value indicating which modifier keys (shift, control, etc.)
268 were held down at the time of the event.
270 The contents of each event are as follows:
279 Which key was pressed. This is an integer (in the printing
280 ASCII range: >32 and <127) or a symbol such as `left' or
281 `right'. Note that many physical keys are actually treated
282 as two separate keys, depending on whether the shift key is
283 pressed; for example, the "a" key is treated as either "a" or
284 "A" depending on the state of the shift key, and the "1" key
285 is similarly treated as either "1" or "!" on most keyboards.
286 In such cases, the shift key does not show up in the modifier
287 list. For other keys, such as `backspace', the shift key
288 shows up as a regular modifier.
291 Which modifier keys were pressed. As mentioned above, the
292 shift key is not treated as a modifier for many keys and will
293 not show up in this list in such cases.
303 What button went down or up. Buttons are numbered starting
307 Which modifier keys were pressed. The special business
308 mentioned above for the shift key does *not* apply to mouse
313 The position of the pointer (in pixels) at the time of the
324 The position of the pointer (in pixels) after it moved.
327 Which modifier keys were pressed. The special business
328 mentioned above for the shift key does *not* apply to mouse
336 The E-Lisp function to call for this event. This is normally
337 either `eval' or `call-interactively'.
340 The object to pass to the function. This is normally the
341 callback that was specified in the menu description.
344 What button went down or up. Buttons are numbered starting
348 Which modifier keys were pressed. The special business
349 mentioned above for the shift key does *not* apply to mouse
354 The position of the pointer (in pixels) at the time of the
362 The Emacs "process" object in question.
369 The E-Lisp function to call for this timeout. It is called
370 with one argument, the event.
373 Some Lisp object associated with this timeout, to make it
374 easier to tell them apart. The function and object for this
375 event were specified when the timeout was set.
380 (The rest of the information in this event is not user-accessible.)
387 An E-Lisp function to call when this event is dispatched.
390 The object to pass to the function. The function and object
391 are set when the event is created.
393 - Function: event-type EVENT
394 Return the type of EVENT.
396 This will be a symbol; one of
402 A mouse button was pressed.
405 A mouse button was released.
411 Some other user action happened; typically, this is a menu
412 selection, scrollbar action, or drag and drop action.
415 Input is available from a subprocess.
418 A timeout has expired.
421 This causes a specified action to occur when dispatched.
424 Some window-system-specific event has occurred.
427 File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events
432 The following predicates return whether an object is an event of a
435 - Function: key-press-event-p OBJECT
436 This is true if OBJECT is a key-press event.
438 - Function: button-event-p OBJECT OBJECT
439 This is true if OBJECT is a mouse button-press or button-release
442 - Function: button-press-event-p OBJECT
443 This is true if OBJECT is a mouse button-press event.
445 - Function: button-release-event-p OBJECT
446 This is true if OBJECT is a mouse button-release event.
448 - Function: motion-event-p OBJECT
449 This is true if OBJECT is a mouse motion event.
451 - Function: mouse-event-p OBJECT
452 This is true if OBJECT is a mouse button-press, button-release or
455 - Function: eval-event-p OBJECT
456 This is true if OBJECT is an eval event.
458 - Function: misc-user-event-p OBJECT
459 This is true if OBJECT is a misc-user event.
461 - Function: process-event-p OBJECT
462 This is true if OBJECT is a process event.
464 - Function: timeout-event-p OBJECT
465 This is true if OBJECT is a timeout event.
467 - Function: event-live-p OBJECT
468 This is true if OBJECT is any event that has not been deallocated.
471 File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events
473 Accessing the Position of a Mouse Event
474 ---------------------------------------
476 Unlike other events, mouse events (i.e. motion, button-press,
477 button-release, and drag or drop type misc-user events) occur in a
478 particular location on the screen. Many primitives are provided for
479 determining exactly where the event occurred and what is under that
484 * Frame-Level Event Position Info::
485 * Window-Level Event Position Info::
486 * Event Text Position Info::
487 * Event Glyph Position Info::
488 * Event Toolbar Position Info::
489 * Other Event Position Info::
492 File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
494 Frame-Level Event Position Info
495 ...............................
497 The following functions return frame-level information about where a
498 mouse event occurred.
500 - Function: event-frame EVENT
501 This function returns the "channel" or frame that the given mouse
502 motion, button press, button release, or misc-user event occurred
503 in. This will be `nil' for non-mouse events.
505 - Function: event-x-pixel EVENT
506 This function returns the X position in pixels of the given mouse
507 event. The value returned is relative to the frame the event
508 occurred in. This will signal an error if the event is not a
511 - Function: event-y-pixel EVENT
512 This function returns the Y position in pixels of the given mouse
513 event. The value returned is relative to the frame the event
514 occurred in. This will signal an error if the event is not a
518 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
520 Window-Level Event Position Info
521 ................................
523 The following functions return window-level information about where
524 a mouse event occurred.
526 - Function: event-window EVENT
527 Given a mouse motion, button press, button release, or misc-user
528 event, compute and return the window on which that event occurred.
529 This may be `nil' if the event occurred in the border or over a
530 toolbar. The modeline is considered to be within the window it
533 - Function: event-buffer EVENT
534 Given a mouse motion, button press, button release, or misc-user
535 event, compute and return the buffer of the window on which that
536 event occurred. This may be `nil' if the event occurred in the
537 border or over a toolbar. The modeline is considered to be within
538 the window it describes. This is equivalent to calling
539 `event-window' and then calling `window-buffer' on the result if
542 - Function: event-window-x-pixel EVENT
543 This function returns the X position in pixels of the given mouse
544 event. The value returned is relative to the window the event
545 occurred in. This will signal an error if the event is not a
546 mouse-motion, button-press, button-release, or misc-user event.
548 - Function: event-window-y-pixel EVENT
549 This function returns the Y position in pixels of the given mouse
550 event. The value returned is relative to the window the event
551 occurred in. This will signal an error if the event is not a
552 mouse-motion, button-press, button-release, or misc-user event.
555 File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
557 Event Text Position Info
558 ........................
560 The following functions return information about the text (including
561 the modeline) that a mouse event occurred over or near.
563 - Function: event-over-text-area-p EVENT
564 Given a mouse-motion, button-press, button-release, or misc-user
565 event, this function returns `t' if the event is over the text
566 area of a window. Otherwise, `nil' is returned. The modeline is
567 not considered to be part of the text area.
569 - Function: event-over-modeline-p EVENT
570 Given a mouse-motion, button-press, button-release, or misc-user
571 event, this function returns `t' if the event is over the modeline
572 of a window. Otherwise, `nil' is returned.
574 - Function: event-x EVENT
575 This function returns the X position of the given mouse-motion,
576 button-press, button-release, or misc-user event in characters.
577 This is relative to the window the event occurred over.
579 - Function: event-y EVENT
580 This function returns the Y position of the given mouse-motion,
581 button-press, button-release, or misc-user event in characters.
582 This is relative to the window the event occurred over.
584 - Function: event-point EVENT
585 This function returns the character position of the given
586 mouse-motion, button-press, button-release, or misc-user event.
587 If the event did not occur over a window, or did not occur over
588 text, then this returns `nil'. Otherwise, it returns an index
589 into the buffer visible in the event's window.
591 - Function: event-closest-point EVENT
592 This function returns the character position of the given
593 mouse-motion, button-press, button-release, or misc-user event.
594 If the event did not occur over a window or over text, it returns
595 the closest point to the location of the event. If the Y pixel
596 position overlaps a window and the X pixel position is to the left
597 of that window, the closest point is the beginning of the line
598 containing the Y position. If the Y pixel position overlaps a
599 window and the X pixel position is to the right of that window,
600 the closest point is the end of the line containing the Y
601 position. If the Y pixel position is above a window, 0 is
602 returned. If it is below a window, the value of `(window-end)' is
606 File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions
608 Event Glyph Position Info
609 .........................
611 The following functions return information about the glyph (if any)
612 that a mouse event occurred over.
614 - Function: event-over-glyph-p EVENT
615 Given a mouse-motion, button-press, button-release, or misc-user
616 event, this function returns `t' if the event is over a glyph.
617 Otherwise, `nil' is returned.
619 - Function: event-glyph-extent EVENT
620 If the given mouse-motion, button-press, button-release, or
621 misc-user event happened on top of a glyph, this returns its
622 extent; else `nil' is returned.
624 - Function: event-glyph-x-pixel EVENT
625 Given a mouse-motion, button-press, button-release, or misc-user
626 event over a glyph, this function returns the X position of the
627 pointer relative to the upper left of the glyph. If the event is
628 not over a glyph, it returns `nil'.
630 - Function: event-glyph-y-pixel EVENT
631 Given a mouse-motion, button-press, button-release, or misc-user
632 event over a glyph, this function returns the Y position of the
633 pointer relative to the upper left of the glyph. If the event is
634 not over a glyph, it returns `nil'.
637 File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions
639 Event Toolbar Position Info
640 ...........................
642 - Function: event-over-toolbar-p EVENT
643 Given a mouse-motion, button-press, button-release, or misc-user
644 event, this function returns `t' if the event is over a toolbar.
645 Otherwise, `nil' is returned.
647 - Function: event-toolbar-button EVENT
648 If the given mouse-motion, button-press, button-release, or
649 misc-user event happened on top of a toolbar button, this function
650 returns the button. Otherwise, `nil' is returned.
653 File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions
655 Other Event Position Info
656 .........................
658 - Function: event-over-border-p EVENT
659 Given a mouse-motion, button-press, button-release, or misc-user
660 event, this function returns `t' if the event is over an internal
661 toolbar. Otherwise, `nil' is returned.
664 File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events
666 Accessing the Other Contents of Events
667 --------------------------------------
669 The following functions allow access to the contents of events other
670 than the position info described in the previous section.
672 - Function: event-timestamp EVENT
673 This function returns the timestamp of the given event object.
675 - Function: event-device EVENT
676 This function returns the device that the given event occurred on.
678 - Function: event-key EVENT
679 This function returns the Keysym of the given key-press event.
680 This will be the ASCII code of a printing character, or a symbol.
682 - Function: event-button EVENT
683 This function returns the button-number of the given button-press
684 or button-release event.
686 - Function: event-modifiers EVENT
687 This function returns a list of symbols, the names of the modifier
688 keys which were down when the given mouse or keyboard event was
691 - Function: event-modifier-bits EVENT
692 This function returns a number representing the modifier keys
693 which were down when the given mouse or keyboard event was
696 - Function: event-function EVENT
697 This function returns the callback function of the given timeout,
698 misc-user, or eval event.
700 - Function: event-object EVENT
701 This function returns the callback function argument of the given
702 timeout, misc-user, or eval event.
704 - Function: event-process EVENT
705 This function returns the process of the given process event.
708 File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events
713 XEmacs provides primitives for creating, copying, and destroying
714 event objects. Many functions that return events take an event object
715 as an argument and fill in the fields of this event; or they make accept
716 either an event object or `nil', creating the event object first in the
719 - Function: make-event &optional TYPE PLIST
720 This function creates a new event structure. If no arguments are
721 specified, the created event will be empty. To specify the event
722 type, use the TYPE argument. The allowed types are `empty',
723 `key-press', `button-press', `button-release', `motion', or
726 PLIST is a property list, the properties being compatible to those
727 returned by `event-properties'. For events other than `empty', it
728 is mandatory to specify certain properties. For `empty' events,
729 PLIST must be `nil'. The list is "canonicalized", which means
730 that if a property keyword is present more than once, only the
731 first instance is taken into account. Specifying an unknown or
732 illegal property signals an error.
734 The following properties are allowed:
737 The event channel. This is a frame or a console. For mouse
738 events (of type `button-press', `button-release' and
739 `motion'), this must be a frame. For key-press events, it
740 must be a console. If channel is unspecified by PLIST, it
741 will be set to the selected frame or selected console, as
745 The event key. This is either a symbol or a character. It
746 is allowed (and required) only for key-press events.
749 The event button. This an integer, either 1, 2 or 3. It is
750 allowed only for button-press and button-release events.
753 The event modifiers. This is a list of modifier symbols. It
754 is allowed for key-press, button-press, button-release and
758 The event X coordinate. This is an integer. It is relative
759 to the channel's root window, and is allowed for
760 button-press, button-release and motion events.
763 The event Y coordinate. This is an integer. It is relative
764 to the channel's root window, and is allowed for
765 button-press, button-release and motion events. This means
766 that, for instance, to access the toolbar, the `y' property
767 will have to be negative.
770 The event timestamp, a non-negative integer. Allowed for all
773 *WARNING*: the event object returned by this function may be a
774 reused one; see the function `deallocate-event'.
776 The events created by `make-event' can be used as non-interactive
777 arguments to the functions with an `(interactive "e")'
780 Here are some basic examples of usage:
782 ;; Create an empty event.
786 ;; Try creating a key-press event.
787 (make-event 'key-press)
788 error--> Undefined key for keypress event
790 ;; Creating a key-press event, try 2
791 (make-event 'key-press '(key home))
792 => #<keypress-event home>
794 ;; Create a key-press event of dubious fame.
795 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
796 => #<keypress-event control-meta-alt-shift-escape>
798 ;; Create a M-button1 event at coordinates defined by variables
800 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
801 => #<buttondown-event meta-button1>
803 ;; Create a similar button-release event.
804 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
805 => #<buttonup-event meta-button1up>
807 ;; Create a mouse-motion event.
808 (make-event 'motion '(x 20 y 30))
809 => #<motion-event 20, 30>
811 (event-properties (make-event 'motion '(x 20 y 30)))
812 => (channel #<x-frame "emacs" 0x8e2> x 20 y 30
813 modifiers nil timestamp 0)
815 In conjunction with `event-properties', you can use `make-event'
816 to create modified copies of existing events. For instance, the
817 following code will return an `equal' copy of EVENT:
819 (make-event (event-type EVENT)
820 (event-properties EVENT))
822 Note, however, that you cannot use `make-event' as the generic
823 replacement for `copy-event', because it does not allow creating
824 all of the event types.
826 To create a modified copy of an event, you can use the
827 canonicalization feature of PLIST. The following example creates
828 a copy of EVENT, but with `modifiers' reset to `nil'.
830 (make-event (event-type EVENT)
831 (append '(modifiers nil)
832 (event-properties EVENT)))
834 - Function: copy-event EVENT1 &optional EVENT2
835 This function makes a copy of the given event object. If a second
836 argument is given, the first event is copied into the second and
837 the second is returned. If the second argument is not supplied
838 (or is `nil') then a new event will be made.
840 - Function: deallocate-event EVENT
841 This function allows the given event structure to be reused. You
842 *MUST NOT* use this event object after calling this function with
843 it. You will lose. It is not necessary to call this function, as
844 event objects are garbage-collected like all other objects;
845 however, it may be more efficient to explicitly deallocate events
846 when you are sure that that is safe.
849 File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
854 XEmacs provides some auxiliary functions for converting between
855 events and other ways of representing keys. These are useful when
856 working with ASCII strings and with keymaps.
858 - Function: character-to-event CH &optional EVENT DEVICE
859 This function converts a numeric ASCII value to an event structure,
860 replete with modifier bits. CH is the character to convert, and
861 EVENT is the event object to fill in. This function contains
862 knowledge about what the codes "mean" - for example, the number 9
863 is converted to the character <Tab>, not the distinct character
866 Note that CH does not have to be a numeric value, but can be a
867 symbol such as `clear' or a list such as `(control backspace)'.
869 If `event' is not `nil', it is modified; otherwise, a new event
870 object is created. In both cases, the event is returned.
872 Optional third arg DEVICE is the device to store in the event;
873 this also affects whether the high bit is interpreted as a meta
874 key. A value of `nil' means use the selected device but always
875 treat the high bit as meta.
877 Beware that `character-to-event' and `event-to-character' are not
878 strictly inverse functions, since events contain much more
879 information than the ASCII character set can encode.
881 - Function: event-to-character EVENT &optional ALLOW-EXTRA-MODIFIERS
882 ALLOW-META ALLOW-NON-ASCII
883 This function returns the closest ASCII approximation to EVENT.
884 If the event isn't a keypress, this returns `nil'.
886 If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
887 translation; it will ignore modifier keys other than <control> and
888 <meta>, and will ignore the <shift> modifier on those characters
889 which have no shifted ASCII equivalent (<Control-Shift-A> for
890 example, will be mapped to the same ASCII code as <Control-A>).
892 If ALLOW-META is non-`nil', then the <Meta> modifier will be
893 represented by turning on the high bit of the byte returned;
894 otherwise, `nil' will be returned for events containing the <Meta>
897 If ALLOW-NON-ASCII is non-`nil', then characters which are present
898 in the prevailing character set (*note variable
899 `character-set-property': Keymaps.) will be returned as their code
900 in that character set, instead of the return value being
903 Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
904 ambiguous, as both use the high bit; <M-x> and <oslash> will be
907 - Function: events-to-keys EVENTS &optional NO-MICE
908 Given a vector of event objects, this function returns a vector of
909 key descriptors, or a string (if they all fit in the ASCII range).
910 Optional arg NO-MICE means that button events are not allowed.
913 File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
918 The editor command loop reads keyboard input using the function
919 `next-event' and constructs key sequences out of the events using
920 `dispatch-event'. Lisp programs can also use the function
921 `read-key-sequence', which reads input a key sequence at a time. See
922 also `momentary-string-display' in *Note Temporary Displays::, and
923 `sit-for' in *Note Waiting::. *Note Terminal Input::, for functions
924 and variables for controlling terminal input modes and debugging
927 For higher-level input facilities, see *Note Minibuffers::.
931 * Key Sequence Input:: How to read one key sequence.
932 * Reading One Event:: How to read just one event.
933 * Dispatching an Event:: What to do with an event once it has been read.
934 * Quoted Character Input:: Asking the user to specify a character.
935 * Peeking and Discarding:: How to reread or throw away input events.
938 File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
943 Lisp programs can read input a key sequence at a time by calling
944 `read-key-sequence'; for example, `describe-key' uses it to read the
947 - Function: read-key-sequence PROMPT
948 This function reads a sequence of keystrokes or mouse clicks and
949 returns it as a vector of events. It keeps reading events until
950 it has accumulated a full key sequence; that is, enough to specify
951 a non-prefix command using the currently active keymaps.
953 The vector and the event objects it contains are freshly created,
954 and will not be side-effected by subsequent calls to this function.
956 The function `read-key-sequence' suppresses quitting: `C-g' typed
957 while reading with this function works like any other character,
958 and does not set `quit-flag'. *Note Quitting::.
960 The argument PROMPT is either a string to be displayed in the echo
961 area as a prompt, or `nil', meaning not to display a prompt.
963 If the user selects a menu item while we are prompting for a key
964 sequence, the returned value will be a vector of a single
965 menu-selection event (a misc-user event). An error will be
966 signalled if you pass this value to `lookup-key' or a related
969 In the example below, the prompt `?' is displayed in the echo area,
970 and the user types `C-x C-f'.
972 (read-key-sequence "?")
974 ---------- Echo Area ----------
976 ---------- Echo Area ----------
978 => [#<keypress-event control-X> #<keypress-event control-F>]
980 If an input character is an upper-case letter and has no key binding,
981 but its lower-case equivalent has one, then `read-key-sequence'
982 converts the character to lower case. Note that `lookup-key' does not
983 perform case conversion in this way.
986 File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
991 The lowest level functions for command input are those which read a
992 single event. These functions often make a distinction between
993 "command events", which are user actions (keystrokes and mouse
994 actions), and other events, which serve as communication between XEmacs
995 and the window system.
997 - Function: next-event &optional EVENT PROMPT
998 This function reads and returns the next available event from the
999 window system or terminal driver, waiting if necessary until an
1000 event is available. Pass this object to `dispatch-event' to
1001 handle it. If an event object is supplied, it is filled in and
1002 returned; otherwise a new event object will be created.
1004 Events can come directly from the user, from a keyboard macro, or
1005 from `unread-command-events'.
1007 In most cases, the function `next-command-event' is more
1010 - Function: next-command-event &optional EVENT
1011 This function returns the next available "user" event from the
1012 window system or terminal driver. Pass this object to
1013 `dispatch-event' to handle it. If an event object is supplied, it
1014 is filled in and returned, otherwise a new event object will be
1017 The event returned will be a keyboard, mouse press, or mouse
1018 release event. If there are non-command events available (mouse
1019 motion, sub-process output, etc) then these will be executed (with
1020 `dispatch-event') and discarded. This function is provided as a
1021 convenience; it is equivalent to the Lisp code
1025 (not (or (key-press-event-p event)
1026 (button-press-event-p event)
1027 (button-release-event-p event)
1028 (menu-event-p event))))
1029 (dispatch-event event))
1031 Here is what happens if you call `next-command-event' and then
1032 press the right-arrow function key:
1034 (next-command-event)
1035 => #<keypress-event right>
1037 - Function: read-char
1038 This function reads and returns a character of command input. If a
1039 mouse click is detected, an error is signalled. The character
1040 typed is returned as an ASCII value. This function is retained for
1041 compatibility with Emacs 18, and is most likely the wrong thing
1042 for you to be using: consider using `next-command-event' instead.
1044 - Function: enqueue-eval-event FUNCTION OBJECT
1045 This function adds an eval event to the back of the queue. The
1046 eval event will be the next event read after all pending events.
1049 File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
1051 Dispatching an Event
1052 --------------------
1054 - Function: dispatch-event EVENT
1055 Given an event object returned by `next-event', this function
1056 executes it. This is the basic function that makes XEmacs respond
1057 to user input; it also deals with notifications from the window
1058 system (such as Expose events).
1061 File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
1063 Quoted Character Input
1064 ----------------------
1066 You can use the function `read-quoted-char' to ask the user to
1067 specify a character, and allow the user to specify a control or meta
1068 character conveniently, either literally or as an octal character code.
1069 The command `quoted-insert' uses this function.
1071 - Function: read-quoted-char &optional PROMPT
1072 This function is like `read-char', except that if the first
1073 character read is an octal digit (0-7), it reads up to two more
1074 octal digits (but stopping if a non-octal digit is found) and
1075 returns the character represented by those digits in octal.
1077 Quitting is suppressed when the first character is read, so that
1078 the user can enter a `C-g'. *Note Quitting::.
1080 If PROMPT is supplied, it specifies a string for prompting the
1081 user. The prompt string is always displayed in the echo area,
1082 followed by a single `-'.
1084 In the following example, the user types in the octal number 177
1085 (which is 127 in decimal).
1087 (read-quoted-char "What character")
1089 ---------- Echo Area ----------
1091 ---------- Echo Area ----------
1096 File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
1098 Miscellaneous Event Input Features
1099 ----------------------------------
1101 This section describes how to "peek ahead" at events without using
1102 them up, how to check for pending input, and how to discard pending
1105 See also the variables `last-command-event' and `last-command-char'
1106 (*Note Command Loop Info::).
1108 - Variable: unread-command-events
1109 This variable holds a list of events waiting to be read as command
1110 input. The events are used in the order they appear in the list,
1111 and removed one by one as they are used.
1113 The variable is needed because in some cases a function reads a
1114 event and then decides not to use it. Storing the event in this
1115 variable causes it to be processed normally, by the command loop
1116 or by the functions to read command input.
1118 For example, the function that implements numeric prefix arguments
1119 reads any number of digits. When it finds a non-digit event, it
1120 must unread the event so that it can be read normally by the
1121 command loop. Likewise, incremental search uses this feature to
1122 unread events with no special meaning in a search, because these
1123 events should exit the search and then execute normally.
1126 - Variable: unread-command-event
1127 This variable holds a single event to be read as command input.
1129 This variable is mostly obsolete now that you can use
1130 `unread-command-events' instead; it exists only to support programs
1131 written for versions of XEmacs prior to 19.12.
1133 - Function: input-pending-p
1134 This function determines whether any command input is currently
1135 available to be read. It returns immediately, with value `t' if
1136 there is available input, `nil' otherwise. On rare occasions it
1137 may return `t' when no input is available.
1139 - Variable: last-input-event
1140 This variable is set to the last keyboard or mouse button event
1143 This variable is off limits: you may not set its value or modify
1144 the event that is its value, as it is destructively modified by
1145 `read-key-sequence'. If you want to keep a pointer to this value,
1146 you must use `copy-event'.
1148 Note that this variable is an alias for `last-input-char' in FSF
1151 In the example below, a character is read (the character `1'). It
1152 becomes the value of `last-input-event', while `C-e' (from the
1153 `C-x C-e' command used to evaluate this expression) remains the
1154 value of `last-command-event'.
1156 (progn (print (next-command-event))
1157 (print last-command-event)
1159 -| #<keypress-event 1>
1160 -| #<keypress-event control-E>
1161 => #<keypress-event 1>
1163 - Variable: last-input-char
1164 If the value of `last-input-event' is a keyboard event, then this
1165 is the nearest ASCII equivalent to it. Remember that there is
1166 *not* a 1:1 mapping between keyboard events and ASCII characters:
1167 the set of keyboard events is much larger, so writing code that
1168 examines this variable to determine what key has been typed is bad
1169 practice, unless you are certain that it will be one of a small
1172 This function exists for compatibility with Emacs version 18.
1174 - Function: discard-input
1175 This function discards the contents of the terminal input buffer
1176 and cancels any keyboard macro that might be in the process of
1177 definition. It returns `nil'.
1179 In the following example, the user may type a number of characters
1180 right after starting the evaluation of the form. After the
1181 `sleep-for' finishes sleeping, `discard-input' discards any
1182 characters typed during the sleep.
1184 (progn (sleep-for 2)
1189 File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
1191 Waiting for Elapsed Time or Input
1192 =================================
1194 The wait functions are designed to wait for a certain amount of time
1195 to pass or until there is input. For example, you may wish to pause in
1196 the middle of a computation to allow the user time to view the display.
1197 `sit-for' pauses and updates the screen, and returns immediately if
1198 input comes in, while `sleep-for' pauses without updating the screen.
1200 Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
1201 two arguments to specify the time (one integer and one float value),
1202 instead of a single argument that can be either an integer or a float.
1204 - Function: sit-for SECONDS &optional NODISP
1205 This function performs redisplay (provided there is no pending
1206 input from the user), then waits SECONDS seconds, or until input is
1207 available. The result is `t' if `sit-for' waited the full time
1208 with no input arriving (see `input-pending-p' in *Note Peeking and
1209 Discarding::). Otherwise, the value is `nil'.
1211 The argument SECONDS need not be an integer. If it is a floating
1212 point number, `sit-for' waits for a fractional number of seconds.
1214 Redisplay is normally preempted if input arrives, and does not
1215 happen at all if input is available before it starts. (You can
1216 force screen updating in such a case by using `force-redisplay'.
1217 *Note Refresh Screen::.) If there is no input pending, you can
1218 force an update with no delay by using `(sit-for 0)'.
1220 If NODISP is non-`nil', then `sit-for' does not redisplay, but it
1221 still returns as soon as input is available (or when the timeout
1224 The usual purpose of `sit-for' is to give the user time to read
1225 text that you display.
1227 - Function: sleep-for SECONDS
1228 This function simply pauses for SECONDS seconds without updating
1229 the display. This function pays no attention to available input.
1232 The argument SECONDS need not be an integer. If it is a floating
1233 point number, `sleep-for' waits for a fractional number of seconds.
1235 Use `sleep-for' when you wish to guarantee a delay.
1237 *Note Time of Day::, for functions to get the current time.
projects / chise / xemacs-chise.git.1 / blob