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: Using Interactive, Next: Interactive Codes, Up: Defining Commands
58 This section describes how to write the `interactive' form that
59 makes a Lisp function an interactively-callable command.
61 - Special Form: interactive arg-descriptor
62 This special form declares that the function in which it appears
63 is a command, and that it may therefore be called interactively
64 (via `M-x' or by entering a key sequence bound to it). The
65 argument ARG-DESCRIPTOR declares how to compute the arguments to
66 the command when the command is called interactively.
68 A command may be called from Lisp programs like any other
69 function, but then the caller supplies the arguments and
70 ARG-DESCRIPTOR has no effect.
72 The `interactive' form has its effect because the command loop
73 (actually, its subroutine `call-interactively') scans through the
74 function definition looking for it, before calling the function.
75 Once the function is called, all its body forms including the
76 `interactive' form are executed, but at this time `interactive'
77 simply returns `nil' without even evaluating its argument.
79 There are three possibilities for the argument ARG-DESCRIPTOR:
81 * It may be omitted or `nil'; then the command is called with no
82 arguments. This leads quickly to an error if the command requires
83 one or more arguments.
85 * It may be a Lisp expression that is not a string; then it should
86 be a form that is evaluated to get a list of arguments to pass to
89 If this expression reads keyboard input (this includes using the
90 minibuffer), keep in mind that the integer value of point or the
91 mark before reading input may be incorrect after reading input.
92 This is because the current buffer may be receiving subprocess
93 output; if subprocess output arrives while the command is waiting
94 for input, it could relocate point and the mark.
96 Here's an example of what _not_ to do:
99 (list (region-beginning) (region-end)
100 (read-string "Foo: " nil 'my-history)))
102 Here's how to avoid the problem, by examining point and the mark
103 only after reading the keyboard input:
106 (let ((string (read-string "Foo: " nil 'my-history)))
107 (list (region-beginning) (region-end) string)))
109 * It may be a string; then its contents should consist of a code
110 character followed by a prompt (which some code characters use and
111 some ignore). The prompt ends either with the end of the string
112 or with a newline. Here is a simple example:
114 (interactive "bFrobnicate buffer: ")
116 The code letter `b' says to read the name of an existing buffer,
117 with completion. The buffer name is the sole argument passed to
118 the command. The rest of the string is a prompt.
120 If there is a newline character in the string, it terminates the
121 prompt. If the string does not end there, then the rest of the
122 string should contain another code character and prompt,
123 specifying another argument. You can specify any number of
124 arguments in this way.
126 The prompt string can use `%' to include previous argument values
127 (starting with the first argument) in the prompt. This is done
128 using `format' (*note Formatting Strings::). For example, here is
129 how you could read the name of an existing buffer followed by a
130 new name to give to that buffer:
132 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
134 If the first character in the string is `*', then an error is
135 signaled if the buffer is read-only.
137 If the first character in the string is `@', and if the key
138 sequence used to invoke the command includes any mouse events, then
139 the window associated with the first of those events is selected
140 before the command is run.
142 If the first character in the string is `_', then this command will
143 not cause the region to be deactivated when it completes; that is,
144 `zmacs-region-stays' will be set to `t' when the command exits
147 You can use `*', `@', and `_' together; the order does not matter.
148 Actual reading of arguments is controlled by the rest of the
149 prompt string (starting with the first character that is not `*',
152 - Function: function-interactive function
153 This function retrieves the interactive specification of FUNCTION,
154 which may be any funcallable object. The specification will be
155 returned as the list of the symbol `interactive' and the specs. If
156 FUNCTION is not interactive, `nil' will be returned.
159 File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
161 Code Characters for `interactive'
162 ---------------------------------
164 The code character descriptions below contain a number of key words,
165 defined here as follows:
168 Provide completion. <TAB>, <SPC>, and <RET> perform name
169 completion because the argument is read using `completing-read'
170 (*note Completion::). `?' displays a list of possible completions.
173 Require the name of an existing object. An invalid name is not
174 accepted; the commands to exit the minibuffer do not exit if the
175 current input is not valid.
178 A default value of some sort is used if the user enters no text in
179 the minibuffer. The default depends on the code character.
182 This code letter computes an argument without reading any input.
183 Therefore, it does not use a prompt string, and any prompt string
184 you supply is ignored.
186 Even though the code letter doesn't use a prompt string, you must
187 follow it with a newline if it is not the last code character in
191 A prompt immediately follows the code character. The prompt ends
192 either with the end of the string or with a newline.
195 This code character is meaningful only at the beginning of the
196 interactive string, and it does not look for a prompt or a newline.
197 It is a single, isolated character.
199 Here are the code character descriptions for use with `interactive':
202 Signal an error if the current buffer is read-only. Special.
205 Select the window mentioned in the first mouse event in the key
206 sequence that invoked this command. Special.
209 Do not cause the region to be deactivated when this command
213 A function name (i.e., a symbol satisfying `fboundp'). Existing,
217 The name of an existing buffer. By default, uses the name of the
218 current buffer (*note Buffers::). Existing, Completion, Default,
222 A buffer name. The buffer need not exist. By default, uses the
223 name of a recently used buffer other than the current buffer.
224 Completion, Default, Prompt.
227 A character. The cursor does not move into the echo area. Prompt.
230 A command name (i.e., a symbol satisfying `commandp'). Existing,
234 The position of point, as an integer (*note Point::). No I/O.
237 A directory name. The default is the current default directory of
238 the current buffer, `default-directory' (*note System
239 Environment::). Existing, Completion, Default, Prompt.
242 The last mouse-button or misc-user event in the key sequence that
243 invoked the command. No I/O.
245 You can use `e' more than once in a single command's interactive
246 specification. If the key sequence that invoked the command has N
247 mouse-button or misc-user events, the Nth `e' provides the Nth
251 A file name of an existing file (*note File Names::). The default
252 directory is `default-directory'. Existing, Completion, Default,
256 A file name. The file need not exist. Completion, Default,
260 A key sequence (*note Keymap Terminology::). This keeps reading
261 events until a command (or undefined command) is found in the
262 current key maps. The key sequence argument is represented as a
263 vector of events. The cursor does not move into the echo area.
266 This kind of input is used by commands such as `describe-key' and
270 A key sequence, whose definition you intend to change. This works
271 like `k', except that it suppresses, for the last input event in
272 the key sequence, the conversions that are normally used (when
273 necessary) to convert an undefined key into a defined one.
276 The position of the mark, as an integer. No I/O.
279 A number read with the minibuffer. If the input is not a number,
280 the user is asked to try again. The prefix argument, if any, is
284 The raw prefix argument. If the prefix argument is `nil', then
285 read a number as with `n'. Requires a number. *Note Prefix
286 Command Arguments::. Prompt.
289 The numeric prefix argument. (Note that this `p' is lower case.)
293 The raw prefix argument. (Note that this `P' is upper case.) No
297 Point and the mark, as two numeric arguments, smallest first.
298 This is the only code letter that specifies two successive
299 arguments rather than one. No I/O.
302 Arbitrary text, read in the minibuffer and returned as a string
303 (*note Text from Minibuffer::). Terminate the input with either
304 <LFD> or <RET>. (`C-q' may be used to include either of these
305 characters in the input.) Prompt.
308 An interned symbol whose name is read in the minibuffer. Any
309 whitespace character terminates the input. (Use `C-q' to include
310 whitespace in the string.) Other characters that normally
311 terminate a symbol (e.g., parentheses and brackets) do not do so
315 A variable declared to be a user option (i.e., satisfying the
316 predicate `user-variable-p'). *Note High-Level Completion::.
317 Existing, Completion, Prompt.
320 A Lisp object, specified with its read syntax, terminated with a
321 <LFD> or <RET>. The object is not evaluated. *Note Object from
322 Minibuffer::. Prompt.
325 A Lisp form is read as with `x', but then evaluated so that its
326 value becomes the argument for the command. Prompt.
329 File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
331 Examples of Using `interactive'
332 -------------------------------
334 Here are some examples of `interactive':
336 (defun foo1 () ; `foo1' takes no arguments,
337 (interactive) ; just moves forward two words.
341 (defun foo2 (n) ; `foo2' takes one argument,
342 (interactive "p") ; which is the numeric prefix.
343 (forward-word (* 2 n)))
346 (defun foo3 (n) ; `foo3' takes one argument,
347 (interactive "nCount:") ; which is read with the Minibuffer.
348 (forward-word (* 2 n)))
351 (defun three-b (b1 b2 b3)
352 "Select three existing buffers.
353 Put them into three windows, selecting the last one."
354 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
355 (delete-other-windows)
356 (split-window (selected-window) 8)
357 (switch-to-buffer b1)
359 (split-window (selected-window) 8)
360 (switch-to-buffer b2)
362 (switch-to-buffer b3))
364 (three-b "*scratch*" "declarations.texi" "*mail*")
368 File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
373 After the command loop has translated a key sequence into a
374 definition, it invokes that definition using the function
375 `command-execute'. If the definition is a function that is a command,
376 `command-execute' calls `call-interactively', which reads the arguments
377 and calls the command. You can also call these functions yourself.
379 - Function: commandp function
380 Returns `t' if FUNCTION is suitable for calling interactively;
381 that is, if FUNCTION is a command. Otherwise, returns `nil'.
383 The interactively callable objects include strings and vectors
384 (treated as keyboard macros), lambda expressions that contain a
385 top-level call to `interactive', compiled-function objects made
386 from such lambda expressions, autoload objects that are declared
387 as interactive (non-`nil' fourth argument to `autoload'), and some
388 of the primitive functions.
390 A symbol is `commandp' if its function definition is `commandp'.
392 Keys and keymaps are not commands. Rather, they are used to look
393 up commands (*note Keymaps::).
395 See `documentation' in *Note Accessing Documentation::, for a
396 realistic example of using `commandp'.
398 - Function: call-interactively command &optional record-flag keys
399 This function calls the interactively callable function COMMAND,
400 reading arguments according to its interactive calling
401 specifications. An error is signaled if COMMAND is not a function
402 or if it cannot be called interactively (i.e., is not a command).
403 Note that keyboard macros (strings and vectors) are not accepted,
404 even though they are considered commands, because they are not
407 If RECORD-FLAG is the symbol `lambda', the interactive calling
408 arguments for COMMAND are read and returned as a list, but the
409 function is not called on them.
411 If RECORD-FLAG is `t', then this command and its arguments are
412 unconditionally added to the list `command-history'. Otherwise,
413 the command is added only if it uses the minibuffer to read an
414 argument. *Note Command History::.
416 - Function: command-execute command &optional record-flag keys
417 This function executes COMMAND as an editing command. The
418 argument COMMAND must satisfy the `commandp' predicate; i.e., it
419 must be an interactively callable function or a keyboard macro.
421 A string or vector as COMMAND is executed with
422 `execute-kbd-macro'. A function is passed to
423 `call-interactively', along with the optional RECORD-FLAG.
425 A symbol is handled by using its function definition in its place.
426 A symbol with an `autoload' definition counts as a command if it
427 was declared to stand for an interactively callable function.
428 Such a definition is handled by loading the specified library and
429 then rechecking the definition of the symbol.
431 - Command: execute-extended-command prefix-argument
432 This function reads a command name from the minibuffer using
433 `completing-read' (*note Completion::). Then it uses
434 `command-execute' to call the specified command. Whatever that
435 command returns becomes the value of `execute-extended-command'.
437 If the command asks for a prefix argument, it receives the value
438 PREFIX-ARGUMENT. If `execute-extended-command' is called
439 interactively, the current raw prefix argument is used for
440 PREFIX-ARGUMENT, and thus passed on to whatever command is run.
442 `execute-extended-command' is the normal definition of `M-x', so
443 it uses the string `M-x ' as a prompt. (It would be better to
444 take the prompt from the events used to invoke
445 `execute-extended-command', but that is painful to implement.) A
446 description of the value of the prefix argument, if any, also
447 becomes part of the prompt.
449 (execute-extended-command 1)
450 ---------- Buffer: Minibuffer ----------
451 1 M-x forward-word RET
452 ---------- Buffer: Minibuffer ----------
455 - Function: interactive-p
456 This function returns `t' if the containing function (the one that
457 called `interactive-p') was called interactively, with the function
458 `call-interactively'. (It makes no difference whether
459 `call-interactively' was called from Lisp or directly from the
460 editor command loop.) If the containing function was called by
461 Lisp evaluation (or with `apply' or `funcall'), then it was not
462 called interactively.
464 The most common use of `interactive-p' is for deciding whether to
465 print an informative message. As a special exception,
466 `interactive-p' returns `nil' whenever a keyboard macro is being
467 run. This is to suppress the informative messages and speed
468 execution of the macro.
480 (setq foobar (list (foo) (interactive-p))))
487 ;; This does not print anything.
493 File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
495 Information from the Command Loop
496 =================================
498 The editor command loop sets several Lisp variables to keep status
499 records for itself and for commands that are run.
501 - Variable: last-command
502 This variable records the name of the previous command executed by
503 the command loop (the one before the current command). Normally
504 the value is a symbol with a function definition, but this is not
507 The value is copied from `this-command' when a command returns to
508 the command loop, except when the command specifies a prefix
509 argument for the following command.
511 - Variable: this-command
512 This variable records the name of the command now being executed by
513 the editor command loop. Like `last-command', it is normally a
514 symbol with a function definition.
516 The command loop sets this variable just before running a command,
517 and copies its value into `last-command' when the command finishes
518 (unless the command specifies a prefix argument for the following
521 Some commands set this variable during their execution, as a flag
522 for whatever command runs next. In particular, the functions for
523 killing text set `this-command' to `kill-region' so that any kill
524 commands immediately following will know to append the killed text
525 to the previous kill.
527 If you do not want a particular command to be recognized as the
528 previous command in the case where it got an error, you must code that
529 command to prevent this. One way is to set `this-command' to `t' at the
530 beginning of the command, and set `this-command' back to its proper
531 value at the end, like this:
535 (let ((old-this-command this-command))
536 (setq this-command t)
538 (setq this-command old-this-command)))
540 - Function: this-command-keys
541 This function returns a vector containing the key and mouse events
542 that invoked the present command, plus any previous commands that
543 generated the prefix argument for this command. (Note: this is not
544 the same as in FSF Emacs, which can return a string.) *Note
547 This function copies the vector and the events; it is safe to keep
551 ;; Now use `C-u C-x C-e' to evaluate that.
552 => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
554 - Variable: last-command-event
555 This variable is set to the last input event that was read by the
556 command loop as part of a command. The principal use of this
557 variable is in `self-insert-command', which uses it to decide which
560 This variable is off limits: you may not set its value or modify
561 the event that is its value, as it is destructively modified by
562 `read-key-sequence'. If you want to keep a pointer to this value,
563 you must use `copy-event'.
565 Note that this variable is an alias for `last-command-char' in FSF
569 ;; Now type `C-u C-x C-e'.
570 => #<keypress-event control-E>
572 - Variable: last-command-char
573 If the value of `last-command-event' is a keyboard event, then this
574 is the nearest character equivalent to it (or `nil' if there is no
575 character equivalent). `last-command-char' is the character that
576 `self-insert-command' will insert in the buffer. Remember that
577 there is _not_ a one-to-one mapping between keyboard events and
578 XEmacs characters: many keyboard events have no corresponding
579 character, and when the Mule feature is available, most characters
580 can not be input on standard keyboards, except possibly with help
581 from an input method. So writing code that examines this variable
582 to determine what key has been typed is bad practice, unless you
583 are certain that it will be one of a small set of characters.
585 This variable exists for compatibility with Emacs version 18.
588 ;; Now use `C-u C-x C-e' to evaluate that.
592 - Variable: current-mouse-event
593 This variable holds the mouse-button event which invoked this
594 command, or `nil'. This is what `(interactive "e")' returns.
596 - Variable: echo-keystrokes
597 This variable determines how much time should elapse before command
598 characters echo. Its value must be an integer, which specifies the
599 number of seconds to wait before echoing. If the user types a
600 prefix key (say `C-x') and then delays this many seconds before
601 continuing, the key `C-x' is echoed in the echo area. Any
602 subsequent characters in the same command will be echoed as well.
604 If the value is zero, then command input is not echoed.
607 File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
612 The XEmacs command loop reads a sequence of "events" that represent
613 keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs,
614 events are a primitive Lisp type that must be manipulated using their
615 own accessor and settor primitives. This section describes the
616 representation and meaning of input events in detail.
618 A key sequence that starts with a mouse event is read using the
619 keymaps of the buffer in the window that the mouse was in, not the
620 current buffer. This does not imply that clicking in a window selects
621 that window or its buffer--that is entirely under the control of the
622 command binding of the key sequence.
624 For information about how exactly the XEmacs command loop works,
625 *Note Reading Input::.
627 - Function: eventp object
628 This function returns non-`nil' if OBJECT is an input event.
632 * Event Types:: Events come in different types.
633 * Event Contents:: What the contents of each event type are.
634 * Event Predicates:: Querying whether an event is of a
636 * Accessing Mouse Event Positions::
637 Determining where a mouse event occurred,
639 * Accessing Other Event Info:: Accessing non-positional event info.
640 * Working With Events:: Creating, copying, and destroying events.
641 * Converting Events:: Converting between events, keys, and
645 File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events
650 Events represent keyboard or mouse activity or status changes of
651 various sorts, such as process input being available or a timeout being
652 triggered. The different event types are as follows:
655 A key was pressed. Note that modifier keys such as "control",
656 "shift", and "alt" do not generate events; instead, they are
657 tracked internally by XEmacs, and non-modifier key presses
658 generate events that specify both the key pressed and the
659 modifiers that were held down at the time.
663 A button was pressed or released. Along with the button that was
664 pressed or released, button events specify the modifier keys that
665 were held down at the time and the position of the pointer at the
669 The pointer was moved. Along with the position of the pointer,
670 these events also specify the modifier keys that were held down at
674 A menu item was selected, the scrollbar was used, or a drag or a
678 Input is available on a process.
681 A timeout has triggered.
684 Some window-system-specific action (such as a frame being resized
685 or a portion of a frame needing to be redrawn) has occurred. The
686 contents of this event are not accessible at the E-Lisp level, but
687 `dispatch-event' knows what to do with an event of this type.
690 This is a special kind of event specifying that a particular
691 function needs to be called when this event is dispatched. An
692 event of this type is sometimes placed in the event queue when a
693 magic event is processed. This kind of event should generally
694 just be passed off to `dispatch-event'. *Note Dispatching an
698 File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events
700 Contents of the Different Types of Events
701 -----------------------------------------
703 Every event, no matter what type it is, contains a timestamp (which
704 is typically an offset in milliseconds from when the X server was
705 started) indicating when the event occurred. In addition, many events
706 contain a "channel", which specifies which frame the event occurred on,
707 and/or a value indicating which modifier keys (shift, control, etc.)
708 were held down at the time of the event.
710 The contents of each event are as follows:
719 Which key was pressed. This is an integer (in the printing
720 ASCII range: >32 and <127) or a symbol such as `left' or
721 `right'. Note that many physical keys are actually treated
722 as two separate keys, depending on whether the shift key is
723 pressed; for example, the "a" key is treated as either "a" or
724 "A" depending on the state of the shift key, and the "1" key
725 is similarly treated as either "1" or "!" on most keyboards.
726 In such cases, the shift key does not show up in the modifier
727 list. For other keys, such as `backspace', the shift key
728 shows up as a regular modifier.
731 Which modifier keys were pressed. As mentioned above, the
732 shift key is not treated as a modifier for many keys and will
733 not show up in this list in such cases.
743 What button went down or up. Buttons are numbered starting
747 Which modifier keys were pressed. The special business
748 mentioned above for the shift key does _not_ apply to mouse
753 The position of the pointer (in pixels) at the time of the
764 The position of the pointer (in pixels) after it moved.
767 Which modifier keys were pressed. The special business
768 mentioned above for the shift key does _not_ apply to mouse
776 The E-Lisp function to call for this event. This is normally
777 either `eval' or `call-interactively'.
780 The object to pass to the function. This is normally the
781 callback that was specified in the menu description.
784 What button went down or up. Buttons are numbered starting
788 Which modifier keys were pressed. The special business
789 mentioned above for the shift key does _not_ apply to mouse
794 The position of the pointer (in pixels) at the time of the
802 The Emacs "process" object in question.
809 The E-Lisp function to call for this timeout. It is called
810 with one argument, the event.
813 Some Lisp object associated with this timeout, to make it
814 easier to tell them apart. The function and object for this
815 event were specified when the timeout was set.
820 (The rest of the information in this event is not user-accessible.)
827 An E-Lisp function to call when this event is dispatched.
830 The object to pass to the function. The function and object
831 are set when the event is created.
833 - Function: event-type event
834 Return the type of EVENT.
836 This will be a symbol; one of
842 A mouse button was pressed.
845 A mouse button was released.
851 Some other user action happened; typically, this is a menu
852 selection, scrollbar action, or drag and drop action.
855 Input is available from a subprocess.
858 A timeout has expired.
861 This causes a specified action to occur when dispatched.
864 Some window-system-specific event has occurred.
867 File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events
872 The following predicates return whether an object is an event of a
875 - Function: key-press-event-p object
876 This is true if OBJECT is a key-press event.
878 - Function: button-event-p object
879 This is true if OBJECT is a mouse button-press or button-release
882 - Function: button-press-event-p object
883 This is true if OBJECT is a mouse button-press event.
885 - Function: button-release-event-p object
886 This is true if OBJECT is a mouse button-release event.
888 - Function: motion-event-p object
889 This is true if OBJECT is a mouse motion event.
891 - Function: mouse-event-p object
892 This is true if OBJECT is a mouse button-press, button-release or
895 - Function: eval-event-p object
896 This is true if OBJECT is an eval event.
898 - Function: misc-user-event-p object
899 This is true if OBJECT is a misc-user event.
901 - Function: process-event-p object
902 This is true if OBJECT is a process event.
904 - Function: timeout-event-p object
905 This is true if OBJECT is a timeout event.
907 - Function: event-live-p object
908 This is true if OBJECT is any event that has not been deallocated.
911 File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events
913 Accessing the Position of a Mouse Event
914 ---------------------------------------
916 Unlike other events, mouse events (i.e. motion, button-press,
917 button-release, and drag or drop type misc-user events) occur in a
918 particular location on the screen. Many primitives are provided for
919 determining exactly where the event occurred and what is under that
924 * Frame-Level Event Position Info::
925 * Window-Level Event Position Info::
926 * Event Text Position Info::
927 * Event Glyph Position Info::
928 * Event Toolbar Position Info::
929 * Other Event Position Info::
932 File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
934 Frame-Level Event Position Info
935 ...............................
937 The following functions return frame-level information about where a
938 mouse event occurred.
940 - Function: event-frame event
941 This function returns the "channel" or frame that the given mouse
942 motion, button press, button release, or misc-user event occurred
943 in. This will be `nil' for non-mouse events.
945 - Function: event-x-pixel event
946 This function returns the X position in pixels of the given mouse
947 event. The value returned is relative to the frame the event
948 occurred in. This will signal an error if the event is not a
951 - Function: event-y-pixel event
952 This function returns the Y position in pixels of the given mouse
953 event. The value returned is relative to the frame the event
954 occurred in. This will signal an error if the event is not a
958 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
960 Window-Level Event Position Info
961 ................................
963 The following functions return window-level information about where
964 a mouse event occurred.
966 - Function: event-window event
967 Given a mouse motion, button press, button release, or misc-user
968 event, compute and return the window on which that event occurred.
969 This may be `nil' if the event occurred in the border or over a
970 toolbar. The modeline is considered to be within the window it
973 - Function: event-buffer event
974 Given a mouse motion, button press, button release, or misc-user
975 event, compute and return the buffer of the window on which that
976 event occurred. This may be `nil' if the event occurred in the
977 border or over a toolbar. The modeline is considered to be within
978 the window it describes. This is equivalent to calling
979 `event-window' and then calling `window-buffer' on the result if
982 - Function: event-window-x-pixel event
983 This function returns the X position in pixels of the given mouse
984 event. The value returned is relative to the window the event
985 occurred in. This will signal an error if the event is not a
986 mouse-motion, button-press, button-release, or misc-user event.
988 - Function: event-window-y-pixel event
989 This function returns the Y position in pixels of the given mouse
990 event. The value returned is relative to the window the event
991 occurred in. This will signal an error if the event is not a
992 mouse-motion, button-press, button-release, or misc-user event.
995 File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
997 Event Text Position Info
998 ........................
1000 The following functions return information about the text (including
1001 the modeline) that a mouse event occurred over or near.
1003 - Function: event-over-text-area-p event
1004 Given a mouse-motion, button-press, button-release, or misc-user
1005 event, this function returns `t' if the event is over the text
1006 area of a window. Otherwise, `nil' is returned. The modeline is
1007 not considered to be part of the text area.
1009 - Function: event-over-modeline-p event
1010 Given a mouse-motion, button-press, button-release, or misc-user
1011 event, this function returns `t' if the event is over the modeline
1012 of a window. Otherwise, `nil' is returned.
1014 - Function: event-x event
1015 This function returns the X position of the given mouse-motion,
1016 button-press, button-release, or misc-user event in characters.
1017 This is relative to the window the event occurred over.
1019 - Function: event-y event
1020 This function returns the Y position of the given mouse-motion,
1021 button-press, button-release, or misc-user event in characters.
1022 This is relative to the window the event occurred over.
1024 - Function: event-point event
1025 This function returns the character position of the given
1026 mouse-motion, button-press, button-release, or misc-user event.
1027 If the event did not occur over a window, or did not occur over
1028 text, then this returns `nil'. Otherwise, it returns an index
1029 into the buffer visible in the event's window.
1031 - Function: event-closest-point event
1032 This function returns the character position of the given
1033 mouse-motion, button-press, button-release, or misc-user event.
1034 If the event did not occur over a window or over text, it returns
1035 the closest point to the location of the event. If the Y pixel
1036 position overlaps a window and the X pixel position is to the left
1037 of that window, the closest point is the beginning of the line
1038 containing the Y position. If the Y pixel position overlaps a
1039 window and the X pixel position is to the right of that window,
1040 the closest point is the end of the line containing the Y
1041 position. If the Y pixel position is above a window, 0 is
1042 returned. If it is below a window, the value of `(window-end)' is
1046 File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions
1048 Event Glyph Position Info
1049 .........................
1051 The following functions return information about the glyph (if any)
1052 that a mouse event occurred over.
1054 - Function: event-over-glyph-p event
1055 Given a mouse-motion, button-press, button-release, or misc-user
1056 event, this function returns `t' if the event is over a glyph.
1057 Otherwise, `nil' is returned.
1059 - Function: event-glyph-extent event
1060 If the given mouse-motion, button-press, button-release, or
1061 misc-user event happened on top of a glyph, this returns its
1062 extent; else `nil' is returned.
1064 - Function: event-glyph-x-pixel event
1065 Given a mouse-motion, button-press, button-release, or misc-user
1066 event over a glyph, this function returns the X position of the
1067 pointer relative to the upper left of the glyph. If the event is
1068 not over a glyph, it returns `nil'.
1070 - Function: event-glyph-y-pixel event
1071 Given a mouse-motion, button-press, button-release, or misc-user
1072 event over a glyph, this function returns the Y position of the
1073 pointer relative to the upper left of the glyph. If the event is
1074 not over a glyph, it returns `nil'.
1077 File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions
1079 Event Toolbar Position Info
1080 ...........................
1082 - Function: event-over-toolbar-p event
1083 Given a mouse-motion, button-press, button-release, or misc-user
1084 event, this function returns `t' if the event is over a toolbar.
1085 Otherwise, `nil' is returned.
1087 - Function: event-toolbar-button event
1088 If the given mouse-motion, button-press, button-release, or
1089 misc-user event happened on top of a toolbar button, this function
1090 returns the button. Otherwise, `nil' is returned.
1093 File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions
1095 Other Event Position Info
1096 .........................
1098 - Function: event-over-border-p event
1099 Given a mouse-motion, button-press, button-release, or misc-user
1100 event, this function returns `t' if the event is over an internal
1101 toolbar. Otherwise, `nil' is returned.
1104 File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events
1106 Accessing the Other Contents of Events
1107 --------------------------------------
1109 The following functions allow access to the contents of events other
1110 than the position info described in the previous section.
1112 - Function: event-timestamp event
1113 This function returns the timestamp of the given event object.
1115 - Function: event-device event
1116 This function returns the device that the given event occurred on.
1118 - Function: event-key event
1119 This function returns the Keysym of the given key-press event.
1120 This will be the ASCII code of a printing character, or a symbol.
1122 - Function: event-button event
1123 This function returns the button-number of the given button-press
1124 or button-release event.
1126 - Function: event-modifiers event
1127 This function returns a list of symbols, the names of the modifier
1128 keys which were down when the given mouse or keyboard event was
1131 - Function: event-modifier-bits event
1132 This function returns a number representing the modifier keys
1133 which were down when the given mouse or keyboard event was
1136 - Function: event-function event
1137 This function returns the callback function of the given timeout,
1138 misc-user, or eval event.
1140 - Function: event-object event
1141 This function returns the callback function argument of the given
1142 timeout, misc-user, or eval event.
1144 - Function: event-process event
1145 This function returns the process of the given process event.
1148 File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events
1153 XEmacs provides primitives for creating, copying, and destroying
1154 event objects. Many functions that return events take an event object
1155 as an argument and fill in the fields of this event; or they make accept
1156 either an event object or `nil', creating the event object first in the
1159 - Function: make-event &optional type plist
1160 This function creates a new event structure. If no arguments are
1161 specified, the created event will be empty. To specify the event
1162 type, use the TYPE argument. The allowed types are `empty',
1163 `key-press', `button-press', `button-release', `motion', or
1166 PLIST is a property list, the properties being compatible to those
1167 returned by `event-properties'. For events other than `empty', it
1168 is mandatory to specify certain properties. For `empty' events,
1169 PLIST must be `nil'. The list is "canonicalized", which means
1170 that if a property keyword is present more than once, only the
1171 first instance is taken into account. Specifying an unknown or
1172 illegal property signals an error.
1174 The following properties are allowed:
1177 The event channel. This is a frame or a console. For mouse
1178 events (of type `button-press', `button-release' and
1179 `motion'), this must be a frame. For key-press events, it
1180 must be a console. If channel is unspecified by PLIST, it
1181 will be set to the selected frame or selected console, as
1185 The event key. This is either a symbol or a character. It
1186 is allowed (and required) only for key-press events.
1189 The event button. This an integer, either 1, 2 or 3. It is
1190 allowed only for button-press and button-release events.
1193 The event modifiers. This is a list of modifier symbols. It
1194 is allowed for key-press, button-press, button-release and
1198 The event X coordinate. This is an integer. It is relative
1199 to the channel's root window, and is allowed for
1200 button-press, button-release and motion events.
1203 The event Y coordinate. This is an integer. It is relative
1204 to the channel's root window, and is allowed for
1205 button-press, button-release and motion events. This means
1206 that, for instance, to access the toolbar, the `y' property
1207 will have to be negative.
1210 The event timestamp, a non-negative integer. Allowed for all
1213 _WARNING_: the event object returned by this function may be a
1214 reused one; see the function `deallocate-event'.
1216 The events created by `make-event' can be used as non-interactive
1217 arguments to the functions with an `(interactive "e")'
1220 Here are some basic examples of usage:
1222 ;; Create an empty event.
1226 ;; Try creating a key-press event.
1227 (make-event 'key-press)
1228 error--> Undefined key for keypress event
1230 ;; Creating a key-press event, try 2
1231 (make-event 'key-press '(key home))
1232 => #<keypress-event home>
1234 ;; Create a key-press event of dubious fame.
1235 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
1236 => #<keypress-event control-meta-alt-shift-escape>
1238 ;; Create a M-button1 event at coordinates defined by variables
1240 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
1241 => #<buttondown-event meta-button1>
1243 ;; Create a similar button-release event.
1244 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
1245 => #<buttonup-event meta-button1up>
1247 ;; Create a mouse-motion event.
1248 (make-event 'motion '(x 20 y 30))
1249 => #<motion-event 20, 30>
1251 (event-properties (make-event 'motion '(x 20 y 30)))
1252 => (channel #<x-frame "emacs" 0x8e2> x 20 y 30
1253 modifiers nil timestamp 0)
1255 In conjunction with `event-properties', you can use `make-event'
1256 to create modified copies of existing events. For instance, the
1257 following code will return an `equal' copy of EVENT:
1259 (make-event (event-type EVENT)
1260 (event-properties EVENT))
1262 Note, however, that you cannot use `make-event' as the generic
1263 replacement for `copy-event', because it does not allow creating
1264 all of the event types.
1266 To create a modified copy of an event, you can use the
1267 canonicalization feature of PLIST. The following example creates
1268 a copy of EVENT, but with `modifiers' reset to `nil'.
1270 (make-event (event-type EVENT)
1271 (append '(modifiers nil)
1272 (event-properties EVENT)))
1274 - Function: copy-event event1 &optional event2
1275 This function makes a copy of the event object EVENT1. If a
1276 second event argument EVENT2 is given, EVENT1 is copied into
1277 EVENT2 and EVENT2 is returned. If EVENT2 is not supplied (or is
1278 `nil') then a new event will be made, as with `make-event'.
1280 - Function: deallocate-event event
1281 This function allows the given event structure to be reused. You
1282 *MUST NOT* use this event object after calling this function with
1283 it. You will lose. It is not necessary to call this function, as
1284 event objects are garbage-collected like all other objects;
1285 however, it may be more efficient to explicitly deallocate events
1286 when you are sure that it is safe to do so.