This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands Using `interactive' ------------------- This section describes how to write the `interactive' form that makes a Lisp function an interactively-callable command. - Special Form: interactive arg-descriptor This special form declares that the function in which it appears is a command, and that it may therefore be called interactively (via `M-x' or by entering a key sequence bound to it). The argument ARG-DESCRIPTOR declares how to compute the arguments to the command when the command is called interactively. A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and ARG-DESCRIPTOR has no effect. The `interactive' form has its effect because the command loop (actually, its subroutine `call-interactively') scans through the function definition looking for it, before calling the function. Once the function is called, all its body forms including the `interactive' form are executed, but at this time `interactive' simply returns `nil' without even evaluating its argument. There are three possibilities for the argument ARG-DESCRIPTOR: * It may be omitted or `nil'; then the command is called with no arguments. This leads quickly to an error if the command requires one or more arguments. * It may be a Lisp expression that is not a string; then it should be a form that is evaluated to get a list of arguments to pass to the command. If this expression reads keyboard input (this includes using the minibuffer), keep in mind that the integer value of point or the mark before reading input may be incorrect after reading input. This is because the current buffer may be receiving subprocess output; if subprocess output arrives while the command is waiting for input, it could relocate point and the mark. Here's an example of what _not_ to do: (interactive (list (region-beginning) (region-end) (read-string "Foo: " nil 'my-history))) Here's how to avoid the problem, by examining point and the mark only after reading the keyboard input: (interactive (let ((string (read-string "Foo: " nil 'my-history))) (list (region-beginning) (region-end) string))) * It may be a string; then its contents should consist of a code character followed by a prompt (which some code characters use and some ignore). The prompt ends either with the end of the string or with a newline. Here is a simple example: (interactive "bFrobnicate buffer: ") The code letter `b' says to read the name of an existing buffer, with completion. The buffer name is the sole argument passed to the command. The rest of the string is a prompt. If there is a newline character in the string, it terminates the prompt. If the string does not end there, then the rest of the string should contain another code character and prompt, specifying another argument. You can specify any number of arguments in this way. The prompt string can use `%' to include previous argument values (starting with the first argument) in the prompt. This is done using `format' (*note Formatting Strings::). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer: (interactive "bBuffer to rename: \nsRename buffer %s to: ") If the first character in the string is `*', then an error is signaled if the buffer is read-only. If the first character in the string is `@', and if the key sequence used to invoke the command includes any mouse events, then the window associated with the first of those events is selected before the command is run. If the first character in the string is `_', then this command will not cause the region to be deactivated when it completes; that is, `zmacs-region-stays' will be set to `t' when the command exits successfully. You can use `*', `@', and `_' together; the order does not matter. Actual reading of arguments is controlled by the rest of the prompt string (starting with the first character that is not `*', `@', or `_'). - Function: function-interactive function This function retrieves the interactive specification of FUNCTION, which may be any funcallable object. The specification will be returned as the list of the symbol `interactive' and the specs. If FUNCTION is not interactive, `nil' will be returned.  File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands Code Characters for `interactive' --------------------------------- The code character descriptions below contain a number of key words, defined here as follows: Completion Provide completion. , , and perform name completion because the argument is read using `completing-read' (*note Completion::). `?' displays a list of possible completions. Existing Require the name of an existing object. An invalid name is not accepted; the commands to exit the minibuffer do not exit if the current input is not valid. Default A default value of some sort is used if the user enters no text in the minibuffer. The default depends on the code character. No I/O This code letter computes an argument without reading any input. Therefore, it does not use a prompt string, and any prompt string you supply is ignored. Even though the code letter doesn't use a prompt string, you must follow it with a newline if it is not the last code character in the string. Prompt A prompt immediately follows the code character. The prompt ends either with the end of the string or with a newline. Special This code character is meaningful only at the beginning of the interactive string, and it does not look for a prompt or a newline. It is a single, isolated character. Here are the code character descriptions for use with `interactive': `*' Signal an error if the current buffer is read-only. Special. `@' Select the window mentioned in the first mouse event in the key sequence that invoked this command. Special. `_' Do not cause the region to be deactivated when this command completes. Special. `a' A function name (i.e., a symbol satisfying `fboundp'). Existing, Completion, Prompt. `b' The name of an existing buffer. By default, uses the name of the current buffer (*note Buffers::). Existing, Completion, Default, Prompt. `B' A buffer name. The buffer need not exist. By default, uses the name of a recently used buffer other than the current buffer. Completion, Default, Prompt. `c' A character. The cursor does not move into the echo area. Prompt. `C' A command name (i.e., a symbol satisfying `commandp'). Existing, Completion, Prompt. `d' The position of point, as an integer (*note Point::). No I/O. `D' A directory name. The default is the current default directory of the current buffer, `default-directory' (*note System Environment::). Existing, Completion, Default, Prompt. `e' The last mouse-button or misc-user event in the key sequence that invoked the command. No I/O. You can use `e' more than once in a single command's interactive specification. If the key sequence that invoked the command has N mouse-button or misc-user events, the Nth `e' provides the Nth such event. `f' A file name of an existing file (*note File Names::). The default directory is `default-directory'. Existing, Completion, Default, Prompt. `F' A file name. The file need not exist. Completion, Default, Prompt. `k' A key sequence (*note Keymap Terminology::). This keeps reading events until a command (or undefined command) is found in the current key maps. The key sequence argument is represented as a vector of events. The cursor does not move into the echo area. Prompt. This kind of input is used by commands such as `describe-key' and `global-set-key'. `K' A key sequence, whose definition you intend to change. This works like `k', except that it suppresses, for the last input event in the key sequence, the conversions that are normally used (when necessary) to convert an undefined key into a defined one. `m' The position of the mark, as an integer. No I/O. `n' A number read with the minibuffer. If the input is not a number, the user is asked to try again. The prefix argument, if any, is not used. Prompt. `N' The raw prefix argument. If the prefix argument is `nil', then read a number as with `n'. Requires a number. *Note Prefix Command Arguments::. Prompt. `p' The numeric prefix argument. (Note that this `p' is lower case.) No I/O. `P' The raw prefix argument. (Note that this `P' is upper case.) No I/O. `r' Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. No I/O. `s' Arbitrary text, read in the minibuffer and returned as a string (*note Text from Minibuffer::). Terminate the input with either or . (`C-q' may be used to include either of these characters in the input.) Prompt. `S' An interned symbol whose name is read in the minibuffer. Any whitespace character terminates the input. (Use `C-q' to include whitespace in the string.) Other characters that normally terminate a symbol (e.g., parentheses and brackets) do not do so here. Prompt. `v' A variable declared to be a user option (i.e., satisfying the predicate `user-variable-p'). *Note High-Level Completion::. Existing, Completion, Prompt. `x' A Lisp object, specified with its read syntax, terminated with a or . The object is not evaluated. *Note Object from Minibuffer::. Prompt. `X' A Lisp form is read as with `x', but then evaluated so that its value becomes the argument for the command. Prompt.  File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands Examples of Using `interactive' ------------------------------- Here are some examples of `interactive': (defun foo1 () ; `foo1' takes no arguments, (interactive) ; just moves forward two words. (forward-word 2)) => foo1 (defun foo2 (n) ; `foo2' takes one argument, (interactive "p") ; which is the numeric prefix. (forward-word (* 2 n))) => foo2 (defun foo3 (n) ; `foo3' takes one argument, (interactive "nCount:") ; which is read with the Minibuffer. (forward-word (* 2 n))) => foo3 (defun three-b (b1 b2 b3) "Select three existing buffers. Put them into three windows, selecting the last one." (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") (delete-other-windows) (split-window (selected-window) 8) (switch-to-buffer b1) (other-window 1) (split-window (selected-window) 8) (switch-to-buffer b2) (other-window 1) (switch-to-buffer b3)) => three-b (three-b "*scratch*" "declarations.texi" "*mail*") => nil  File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop Interactive Call ================ After the command loop has translated a key sequence into a definition, it invokes that definition using the function `command-execute'. If the definition is a function that is a command, `command-execute' calls `call-interactively', which reads the arguments and calls the command. You can also call these functions yourself. - Function: commandp function Returns `t' if FUNCTION is suitable for calling interactively; that is, if FUNCTION is a command. Otherwise, returns `nil'. The interactively callable objects include strings and vectors (treated as keyboard macros), lambda expressions that contain a top-level call to `interactive', compiled-function objects made from such lambda expressions, autoload objects that are declared as interactive (non-`nil' fourth argument to `autoload'), and some of the primitive functions. A symbol is `commandp' if its function definition is `commandp'. Keys and keymaps are not commands. Rather, they are used to look up commands (*note Keymaps::). See `documentation' in *Note Accessing Documentation::, for a realistic example of using `commandp'. - Function: call-interactively command &optional record-flag keys This function calls the interactively callable function COMMAND, reading arguments according to its interactive calling specifications. An error is signaled if COMMAND is not a function or if it cannot be called interactively (i.e., is not a command). Note that keyboard macros (strings and vectors) are not accepted, even though they are considered commands, because they are not functions. If RECORD-FLAG is the symbol `lambda', the interactive calling arguments for COMMAND are read and returned as a list, but the function is not called on them. If RECORD-FLAG is `t', then this command and its arguments are unconditionally added to the list `command-history'. Otherwise, the command is added only if it uses the minibuffer to read an argument. *Note Command History::. - Function: command-execute command &optional record-flag keys This function executes COMMAND as an editing command. The argument COMMAND must satisfy the `commandp' predicate; i.e., it must be an interactively callable function or a keyboard macro. A string or vector as COMMAND is executed with `execute-kbd-macro'. A function is passed to `call-interactively', along with the optional RECORD-FLAG. A symbol is handled by using its function definition in its place. A symbol with an `autoload' definition counts as a command if it was declared to stand for an interactively callable function. Such a definition is handled by loading the specified library and then rechecking the definition of the symbol. - Command: execute-extended-command prefix-argument This function reads a command name from the minibuffer using `completing-read' (*note Completion::). Then it uses `command-execute' to call the specified command. Whatever that command returns becomes the value of `execute-extended-command'. If the command asks for a prefix argument, it receives the value PREFIX-ARGUMENT. If `execute-extended-command' is called interactively, the current raw prefix argument is used for PREFIX-ARGUMENT, and thus passed on to whatever command is run. `execute-extended-command' is the normal definition of `M-x', so it uses the string `M-x ' as a prompt. (It would be better to take the prompt from the events used to invoke `execute-extended-command', but that is painful to implement.) A description of the value of the prefix argument, if any, also becomes part of the prompt. (execute-extended-command 1) ---------- Buffer: Minibuffer ---------- 1 M-x forward-word RET ---------- Buffer: Minibuffer ---------- => t - Function: interactive-p This function returns `t' if the containing function (the one that called `interactive-p') was called interactively, with the function `call-interactively'. (It makes no difference whether `call-interactively' was called from Lisp or directly from the editor command loop.) If the containing function was called by Lisp evaluation (or with `apply' or `funcall'), then it was not called interactively. The most common use of `interactive-p' is for deciding whether to print an informative message. As a special exception, `interactive-p' returns `nil' whenever a keyboard macro is being run. This is to suppress the informative messages and speed execution of the macro. For example: (defun foo () (interactive) (and (interactive-p) (message "foo"))) => foo (defun bar () (interactive) (setq foobar (list (foo) (interactive-p)))) => bar ;; Type `M-x foo'. -| foo ;; Type `M-x bar'. ;; This does not print anything. foobar => (nil t)  File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop Information from the Command Loop ================================= The editor command loop sets several Lisp variables to keep status records for itself and for commands that are run. - Variable: last-command This variable records the name of the previous command executed by the command loop (the one before the current command). Normally the value is a symbol with a function definition, but this is not guaranteed. The value is copied from `this-command' when a command returns to the command loop, except when the command specifies a prefix argument for the following command. - Variable: this-command This variable records the name of the command now being executed by the editor command loop. Like `last-command', it is normally a symbol with a function definition. The command loop sets this variable just before running a command, and copies its value into `last-command' when the command finishes (unless the command specifies a prefix argument for the following command). Some commands set this variable during their execution, as a flag for whatever command runs next. In particular, the functions for killing text set `this-command' to `kill-region' so that any kill commands immediately following will know to append the killed text to the previous kill. If you do not want a particular command to be recognized as the previous command in the case where it got an error, you must code that command to prevent this. One way is to set `this-command' to `t' at the beginning of the command, and set `this-command' back to its proper value at the end, like this: (defun foo (args...) (interactive ...) (let ((old-this-command this-command)) (setq this-command t) ...do the work... (setq this-command old-this-command))) - Function: this-command-keys This function returns a vector containing the key and mouse events that invoked the present command, plus any previous commands that generated the prefix argument for this command. (Note: this is not the same as in FSF Emacs, which can return a string.) *Note Events::. This function copies the vector and the events; it is safe to keep and modify them. (this-command-keys) ;; Now use `C-u C-x C-e' to evaluate that. => [# # #] - Variable: last-command-event This variable is set to the last input event that was read by the command loop as part of a command. The principal use of this variable is in `self-insert-command', which uses it to decide which character to insert. This variable is off limits: you may not set its value or modify the event that is its value, as it is destructively modified by `read-key-sequence'. If you want to keep a pointer to this value, you must use `copy-event'. Note that this variable is an alias for `last-command-char' in FSF Emacs. last-command-event ;; Now type `C-u C-x C-e'. => # - Variable: last-command-char If the value of `last-command-event' is a keyboard event, then this is the nearest character equivalent to it (or `nil' if there is no character equivalent). `last-command-char' is the character that `self-insert-command' will insert in the buffer. Remember that there is _not_ a one-to-one mapping between keyboard events and XEmacs characters: many keyboard events have no corresponding character, and when the Mule feature is available, most characters can not be input on standard keyboards, except possibly with help from an input method. So writing code that examines this variable to determine what key has been typed is bad practice, unless you are certain that it will be one of a small set of characters. This variable exists for compatibility with Emacs version 18. last-command-char ;; Now use `C-u C-x C-e' to evaluate that. => ?\^E - Variable: current-mouse-event This variable holds the mouse-button event which invoked this command, or `nil'. This is what `(interactive "e")' returns. - Variable: echo-keystrokes This variable determines how much time should elapse before command characters echo. Its value must be an integer, which specifies the number of seconds to wait before echoing. If the user types a prefix key (say `C-x') and then delays this many seconds before continuing, the key `C-x' is echoed in the echo area. Any subsequent characters in the same command will be echoed as well. If the value is zero, then command input is not echoed.  File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop Events ====== The XEmacs command loop reads a sequence of "events" that represent keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs, events are a primitive Lisp type that must be manipulated using their own accessor and settor primitives. This section describes the representation and meaning of input events in detail. A key sequence that starts with a mouse event is read using the keymaps of the buffer in the window that the mouse was in, not the current buffer. This does not imply that clicking in a window selects that window or its buffer--that is entirely under the control of the command binding of the key sequence. For information about how exactly the XEmacs command loop works, *Note Reading Input::. - Function: eventp object This function returns non-`nil' if OBJECT is an input event. * Menu: * Event Types:: Events come in different types. * Event Contents:: What the contents of each event type are. * Event Predicates:: Querying whether an event is of a particular type. * Accessing Mouse Event Positions:: Determining where a mouse event occurred, and over what. * Accessing Other Event Info:: Accessing non-positional event info. * Working With Events:: Creating, copying, and destroying events. * Converting Events:: Converting between events, keys, and characters.  File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events Event Types ----------- Events represent keyboard or mouse activity or status changes of various sorts, such as process input being available or a timeout being triggered. The different event types are as follows: key-press event A key was pressed. Note that modifier keys such as "control", "shift", and "alt" do not generate events; instead, they are tracked internally by XEmacs, and non-modifier key presses generate events that specify both the key pressed and the modifiers that were held down at the time. button-press event button-release event A button was pressed or released. Along with the button that was pressed or released, button events specify the modifier keys that were held down at the time and the position of the pointer at the time. motion event The pointer was moved. Along with the position of the pointer, these events also specify the modifier keys that were held down at the time. misc-user event A menu item was selected, the scrollbar was used, or a drag or a drop occurred. process event Input is available on a process. timeout event A timeout has triggered. magic event Some window-system-specific action (such as a frame being resized or a portion of a frame needing to be redrawn) has occurred. The contents of this event are not accessible at the E-Lisp level, but `dispatch-event' knows what to do with an event of this type. eval event This is a special kind of event specifying that a particular function needs to be called when this event is dispatched. An event of this type is sometimes placed in the event queue when a magic event is processed. This kind of event should generally just be passed off to `dispatch-event'. *Note Dispatching an Event::.  File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events Contents of the Different Types of Events ----------------------------------------- Every event, no matter what type it is, contains a timestamp (which is typically an offset in milliseconds from when the X server was started) indicating when the event occurred. In addition, many events contain a "channel", which specifies which frame the event occurred on, and/or a value indicating which modifier keys (shift, control, etc.) were held down at the time of the event. The contents of each event are as follows: key-press event channel timestamp key Which key was pressed. This is an integer (in the printing ASCII range: >32 and <127) or a symbol such as `left' or `right'. Note that many physical keys are actually treated as two separate keys, depending on whether the shift key is pressed; for example, the "a" key is treated as either "a" or "A" depending on the state of the shift key, and the "1" key is similarly treated as either "1" or "!" on most keyboards. In such cases, the shift key does not show up in the modifier list. For other keys, such as `backspace', the shift key shows up as a regular modifier. modifiers Which modifier keys were pressed. As mentioned above, the shift key is not treated as a modifier for many keys and will not show up in this list in such cases. button-press event button-release event channel timestamp button What button went down or up. Buttons are numbered starting at 1. modifiers Which modifier keys were pressed. The special business mentioned above for the shift key does _not_ apply to mouse events. x y The position of the pointer (in pixels) at the time of the event. pointer-motion event channel timestamp x y The position of the pointer (in pixels) after it moved. modifiers Which modifier keys were pressed. The special business mentioned above for the shift key does _not_ apply to mouse events. misc-user event timestamp function The E-Lisp function to call for this event. This is normally either `eval' or `call-interactively'. object The object to pass to the function. This is normally the callback that was specified in the menu description. button What button went down or up. Buttons are numbered starting at 1. modifiers Which modifier keys were pressed. The special business mentioned above for the shift key does _not_ apply to mouse events. x y The position of the pointer (in pixels) at the time of the event. process_event timestamp process The Emacs "process" object in question. timeout event timestamp function The E-Lisp function to call for this timeout. It is called with one argument, the event. object Some Lisp object associated with this timeout, to make it easier to tell them apart. The function and object for this event were specified when the timeout was set. magic event timestamp (The rest of the information in this event is not user-accessible.) eval event timestamp function An E-Lisp function to call when this event is dispatched. object The object to pass to the function. The function and object are set when the event is created. - Function: event-type event Return the type of EVENT. This will be a symbol; one of `key-press' A key was pressed. `button-press' A mouse button was pressed. `button-release' A mouse button was released. `motion' The mouse moved. `misc-user' Some other user action happened; typically, this is a menu selection, scrollbar action, or drag and drop action. `process' Input is available from a subprocess. `timeout' A timeout has expired. `eval' This causes a specified action to occur when dispatched. `magic' Some window-system-specific event has occurred.  File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events Event Predicates ---------------- The following predicates return whether an object is an event of a particular type. - Function: key-press-event-p object This is true if OBJECT is a key-press event. - Function: button-event-p object This is true if OBJECT is a mouse button-press or button-release event. - Function: button-press-event-p object This is true if OBJECT is a mouse button-press event. - Function: button-release-event-p object This is true if OBJECT is a mouse button-release event. - Function: motion-event-p object This is true if OBJECT is a mouse motion event. - Function: mouse-event-p object This is true if OBJECT is a mouse button-press, button-release or motion event. - Function: eval-event-p object This is true if OBJECT is an eval event. - Function: misc-user-event-p object This is true if OBJECT is a misc-user event. - Function: process-event-p object This is true if OBJECT is a process event. - Function: timeout-event-p object This is true if OBJECT is a timeout event. - Function: event-live-p object This is true if OBJECT is any event that has not been deallocated.  File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events Accessing the Position of a Mouse Event --------------------------------------- Unlike other events, mouse events (i.e. motion, button-press, button-release, and drag or drop type misc-user events) occur in a particular location on the screen. Many primitives are provided for determining exactly where the event occurred and what is under that location. * Menu: * Frame-Level Event Position Info:: * Window-Level Event Position Info:: * Event Text Position Info:: * Event Glyph Position Info:: * Event Toolbar Position Info:: * Other Event Position Info::  File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions Frame-Level Event Position Info ............................... The following functions return frame-level information about where a mouse event occurred. - Function: event-frame event This function returns the "channel" or frame that the given mouse motion, button press, button release, or misc-user event occurred in. This will be `nil' for non-mouse events. - Function: event-x-pixel event This function returns the X position in pixels of the given mouse event. The value returned is relative to the frame the event occurred in. This will signal an error if the event is not a mouse event. - Function: event-y-pixel event This function returns the Y position in pixels of the given mouse event. The value returned is relative to the frame the event occurred in. This will signal an error if the event is not a mouse event.  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 Window-Level Event Position Info ................................ The following functions return window-level information about where a mouse event occurred. - Function: event-window event Given a mouse motion, button press, button release, or misc-user event, compute and return the window on which that event occurred. This may be `nil' if the event occurred in the border or over a toolbar. The modeline is considered to be within the window it describes. - Function: event-buffer event Given a mouse motion, button press, button release, or misc-user event, compute and return the buffer of the window on which that event occurred. This may be `nil' if the event occurred in the border or over a toolbar. The modeline is considered to be within the window it describes. This is equivalent to calling `event-window' and then calling `window-buffer' on the result if it is a window. - Function: event-window-x-pixel event This function returns the X position in pixels of the given mouse event. The value returned is relative to the window the event occurred in. This will signal an error if the event is not a mouse-motion, button-press, button-release, or misc-user event. - Function: event-window-y-pixel event This function returns the Y position in pixels of the given mouse event. The value returned is relative to the window the event occurred in. This will signal an error if the event is not a mouse-motion, button-press, button-release, or misc-user event.  File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions Event Text Position Info ........................ The following functions return information about the text (including the modeline) that a mouse event occurred over or near. - Function: event-over-text-area-p event Given a mouse-motion, button-press, button-release, or misc-user event, this function returns `t' if the event is over the text area of a window. Otherwise, `nil' is returned. The modeline is not considered to be part of the text area. - Function: event-over-modeline-p event Given a mouse-motion, button-press, button-release, or misc-user event, this function returns `t' if the event is over the modeline of a window. Otherwise, `nil' is returned. - Function: event-x event This function returns the X position of the given mouse-motion, button-press, button-release, or misc-user event in characters. This is relative to the window the event occurred over. - Function: event-y event This function returns the Y position of the given mouse-motion, button-press, button-release, or misc-user event in characters. This is relative to the window the event occurred over. - Function: event-point event This function returns the character position of the given mouse-motion, button-press, button-release, or misc-user event. If the event did not occur over a window, or did not occur over text, then this returns `nil'. Otherwise, it returns an index into the buffer visible in the event's window. - Function: event-closest-point event This function returns the character position of the given mouse-motion, button-press, button-release, or misc-user event. If the event did not occur over a window or over text, it returns the closest point to the location of the event. If the Y pixel position overlaps a window and the X pixel position is to the left of that window, the closest point is the beginning of the line containing the Y position. If the Y pixel position overlaps a window and the X pixel position is to the right of that window, the closest point is the end of the line containing the Y position. If the Y pixel position is above a window, 0 is returned. If it is below a window, the value of `(window-end)' is returned.  File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions Event Glyph Position Info ......................... The following functions return information about the glyph (if any) that a mouse event occurred over. - Function: event-over-glyph-p event Given a mouse-motion, button-press, button-release, or misc-user event, this function returns `t' if the event is over a glyph. Otherwise, `nil' is returned. - Function: event-glyph-extent event If the given mouse-motion, button-press, button-release, or misc-user event happened on top of a glyph, this returns its extent; else `nil' is returned. - Function: event-glyph-x-pixel event Given a mouse-motion, button-press, button-release, or misc-user event over a glyph, this function returns the X position of the pointer relative to the upper left of the glyph. If the event is not over a glyph, it returns `nil'. - Function: event-glyph-y-pixel event Given a mouse-motion, button-press, button-release, or misc-user event over a glyph, this function returns the Y position of the pointer relative to the upper left of the glyph. If the event is not over a glyph, it returns `nil'.  File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions Event Toolbar Position Info ........................... - Function: event-over-toolbar-p event Given a mouse-motion, button-press, button-release, or misc-user event, this function returns `t' if the event is over a toolbar. Otherwise, `nil' is returned. - Function: event-toolbar-button event If the given mouse-motion, button-press, button-release, or misc-user event happened on top of a toolbar button, this function returns the button. Otherwise, `nil' is returned.  File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions Other Event Position Info ......................... - Function: event-over-border-p event Given a mouse-motion, button-press, button-release, or misc-user event, this function returns `t' if the event is over an internal toolbar. Otherwise, `nil' is returned.  File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events Accessing the Other Contents of Events -------------------------------------- The following functions allow access to the contents of events other than the position info described in the previous section. - Function: event-timestamp event This function returns the timestamp of the given event object. - Function: event-device event This function returns the device that the given event occurred on. - Function: event-key event This function returns the Keysym of the given key-press event. This will be the ASCII code of a printing character, or a symbol. - Function: event-button event This function returns the button-number of the given button-press or button-release event. - Function: event-modifiers event This function returns a list of symbols, the names of the modifier keys which were down when the given mouse or keyboard event was produced. - Function: event-modifier-bits event This function returns a number representing the modifier keys which were down when the given mouse or keyboard event was produced. - Function: event-function event This function returns the callback function of the given timeout, misc-user, or eval event. - Function: event-object event This function returns the callback function argument of the given timeout, misc-user, or eval event. - Function: event-process event This function returns the process of the given process event.  File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events Working With Events ------------------- XEmacs provides primitives for creating, copying, and destroying event objects. Many functions that return events take an event object as an argument and fill in the fields of this event; or they make accept either an event object or `nil', creating the event object first in the latter case. - Function: make-event &optional type plist This function creates a new event structure. If no arguments are specified, the created event will be empty. To specify the event type, use the TYPE argument. The allowed types are `empty', `key-press', `button-press', `button-release', `motion', or `misc-user'. PLIST is a property list, the properties being compatible to those returned by `event-properties'. For events other than `empty', it is mandatory to specify certain properties. For `empty' events, PLIST must be `nil'. The list is "canonicalized", which means that if a property keyword is present more than once, only the first instance is taken into account. Specifying an unknown or illegal property signals an error. The following properties are allowed: `channel' The event channel. This is a frame or a console. For mouse events (of type `button-press', `button-release' and `motion'), this must be a frame. For key-press events, it must be a console. If channel is unspecified by PLIST, it will be set to the selected frame or selected console, as appropriate. `key' The event key. This is either a symbol or a character. It is allowed (and required) only for key-press events. `button' The event button. This an integer, either 1, 2 or 3. It is allowed only for button-press and button-release events. `modifiers' The event modifiers. This is a list of modifier symbols. It is allowed for key-press, button-press, button-release and motion events. `x' The event X coordinate. This is an integer. It is relative to the channel's root window, and is allowed for button-press, button-release and motion events. `y' The event Y coordinate. This is an integer. It is relative to the channel's root window, and is allowed for button-press, button-release and motion events. This means that, for instance, to access the toolbar, the `y' property will have to be negative. `timestamp' The event timestamp, a non-negative integer. Allowed for all types of events. _WARNING_: the event object returned by this function may be a reused one; see the function `deallocate-event'. The events created by `make-event' can be used as non-interactive arguments to the functions with an `(interactive "e")' specification. Here are some basic examples of usage: ;; Create an empty event. (make-event) => # ;; Try creating a key-press event. (make-event 'key-press) error--> Undefined key for keypress event ;; Creating a key-press event, try 2 (make-event 'key-press '(key home)) => # ;; Create a key-press event of dubious fame. (make-event 'key-press '(key escape modifiers (meta alt control shift))) => # ;; Create a M-button1 event at coordinates defined by variables ;; X and Y. (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y)) => # ;; Create a similar button-release event. (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x)) => # ;; Create a mouse-motion event. (make-event 'motion '(x 20 y 30)) => # (event-properties (make-event 'motion '(x 20 y 30))) => (channel # x 20 y 30 modifiers nil timestamp 0) In conjunction with `event-properties', you can use `make-event' to create modified copies of existing events. For instance, the following code will return an `equal' copy of EVENT: (make-event (event-type EVENT) (event-properties EVENT)) Note, however, that you cannot use `make-event' as the generic replacement for `copy-event', because it does not allow creating all of the event types. To create a modified copy of an event, you can use the canonicalization feature of PLIST. The following example creates a copy of EVENT, but with `modifiers' reset to `nil'. (make-event (event-type EVENT) (append '(modifiers nil) (event-properties EVENT))) - Function: copy-event event1 &optional event2 This function makes a copy of the event object EVENT1. If a second event argument EVENT2 is given, EVENT1 is copied into EVENT2 and EVENT2 is returned. If EVENT2 is not supplied (or is `nil') then a new event will be made, as with `make-event'. - Function: deallocate-event event This function allows the given event structure to be reused. You *MUST NOT* use this event object after calling this function with it. You will lose. It is not necessary to call this function, as event objects are garbage-collected like all other objects; however, it may be more efficient to explicitly deallocate events when you are sure that it is safe to do so.