X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-18;h=229eec8c2cd6a4c885d15dc681687eb187425d6f;hb=70241ad4f7ff48fd1aa7c62c4b72fa18463f6aee;hp=937c3dfee55e3f67443ee9e1a53c57c9dcecf1be;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-18 b/info/lispref.info-18 index 937c3df..229eec8 100644 --- a/info/lispref.info-18 +++ b/info/lispref.info-18 @@ -1,5 +1,5 @@ -This is Info file ../../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0b from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,6 +50,420 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events + +Converting Events +----------------- + + XEmacs provides some auxiliary functions for converting between +events and other ways of representing keys. These are useful when +working with ASCII strings and with keymaps. + + - Function: character-to-event key-description &optional event console + use-console-meta-flag + This function converts a keystroke description to an event + structure. KEY-DESCRIPTION is the specification of a key stroke, + and EVENT is the event object to fill in. This function contains + knowledge about what the codes "mean"--for example, the number 9 is + converted to the character , not the distinct character + . + + Note that KEY-DESCRIPTION can be an integer, a character, a symbol + such as `clear' or a list such as `(control backspace)'. + + If optional arg EVENT is non-`nil', it is modified; otherwise, a + new event object is created. In both cases, the event is returned. + + Optional third arg CONSOLE is the console to store in the event, + and defaults to the selected console. + + If KEY-DESCRIPTION is an integer or character, the high bit may be + interpreted as the meta key. (This is done for backward + compatibility in lots of places.) If USE-CONSOLE-META-FLAG is + `nil', this will always be the case. If USE-CONSOLE-META-FLAG is + non-`nil', the `meta' flag for CONSOLE affects whether the high + bit is interpreted as a meta key. (See `set-input-mode'.) If you + don't want this silly meta interpretation done, you should pass in + a list containing the character. + + Beware that `character-to-event' and `event-to-character' are not + strictly inverse functions, since events contain much more + information than the ASCII character set can encode. + + - Function: event-to-character event &optional allow-extra-modifiers + allow-meta allow-non-ascii + This function returns the closest ASCII approximation to EVENT. + If the event isn't a keypress, this returns `nil'. + + If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its + translation; it will ignore modifier keys other than and + , and will ignore the modifier on those characters + which have no shifted ASCII equivalent ( for + example, will be mapped to the same ASCII code as ). + + If ALLOW-META is non-`nil', then the modifier will be + represented by turning on the high bit of the byte returned; + otherwise, `nil' will be returned for events containing the + modifier. + + If ALLOW-NON-ASCII is non-`nil', then characters which are present + in the prevailing character set (*note variable + `character-set-property': Keymaps.) will be returned as their code + in that character set, instead of the return value being + restricted to ASCII. + + Note that specifying both ALLOW-META and ALLOW-NON-ASCII is + ambiguous, as both use the high bit; and will be + indistinguishable. + + - Function: events-to-keys events &optional no-mice + Given a vector of event objects, this function returns a vector of + key descriptors, or a string (if they all fit in the ASCII range). + Optional arg NO-MICE means that button events are not allowed. + + +File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop + +Reading Input +============= + + The editor command loop reads keyboard input using the function +`next-event' and constructs key sequences out of the events using +`dispatch-event'. Lisp programs can also use the function +`read-key-sequence', which reads input a key sequence at a time. See +also `momentary-string-display' in *Note Temporary Displays::, and +`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions +and variables for controlling terminal input modes and debugging +terminal input. + + For higher-level input facilities, see *Note Minibuffers::. + +* Menu: + +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Dispatching an Event:: What to do with an event once it has been read. +* Quoted Character Input:: Asking the user to specify a character. +* Peeking and Discarding:: How to reread or throw away input events. + + +File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input + +Key Sequence Input +------------------ + + Lisp programs can read input a key sequence at a time by calling +`read-key-sequence'; for example, `describe-key' uses it to read the +key to describe. + + - Function: read-key-sequence prompt &optional continue-echo + dont-downcase-last + This function reads a sequence of keystrokes or mouse clicks and + returns it as a vector of event objects read. It keeps reading + events until it has accumulated a full key sequence; that is, + enough to specify a non-prefix command using the currently active + keymaps. + + The vector and the event objects it contains are freshly created + (and so will not be side-effected by subsequent calls to this + function). + + The function `read-key-sequence' suppresses quitting: `C-g' typed + while reading with this function works like any other character, + and does not set `quit-flag'. *Note Quitting::. + + The argument PROMPT is either a string to be displayed in the echo + area as a prompt, or `nil', meaning not to display a prompt. + + Second optional arg CONTINUE-ECHO non-`nil' means this key echoes + as a continuation of the previous key. + + Third optional arg DONT-DOWNCASE-LAST non-`nil' means do not + convert the last event to lower case. (Normally any upper case + event is converted to lower case if the original event is + undefined and the lower case equivalent is defined.) This argument + is provided mostly for FSF compatibility; the equivalent effect + can be achieved more generally by binding + `retry-undefined-key-binding-unshifted' to `nil' around the call + to `read-key-sequence'. + + If the user selects a menu item while we are prompting for a key + sequence, the returned value will be a vector of a single + menu-selection event (a misc-user event). An error will be + signalled if you pass this value to `lookup-key' or a related + function. + + In the example below, the prompt `?' is displayed in the echo area, + and the user types `C-x C-f'. + + (read-key-sequence "?") + + ---------- Echo Area ---------- + ?C-x C-f + ---------- Echo Area ---------- + + => [# #] + + If an input character is an upper-case letter and has no key binding, +but its lower-case equivalent has one, then `read-key-sequence' +converts the character to lower case. Note that `lookup-key' does not +perform case conversion in this way. + + +File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input + +Reading One Event +----------------- + + The lowest level functions for command input are those which read a +single event. These functions often make a distinction between +"command events", which are user actions (keystrokes and mouse +actions), and other events, which serve as communication between XEmacs +and the window system. + + - Function: next-event &optional event prompt + This function reads and returns the next available event from the + window system or terminal driver, waiting if necessary until an + event is available. Pass this object to `dispatch-event' to + handle it. If an event object is supplied, it is filled in and + returned; otherwise a new event object will be created. + + Events can come directly from the user, from a keyboard macro, or + from `unread-command-events'. + + In most cases, the function `next-command-event' is more + appropriate. + + - Function: next-command-event &optional event prompt + This function returns the next available "user" event from the + window system or terminal driver. Pass this object to + `dispatch-event' to handle it. If an event object is supplied, it + is filled in and returned, otherwise a new event object will be + created. + + The event returned will be a keyboard, mouse press, or mouse + release event. If there are non-command events available (mouse + motion, sub-process output, etc) then these will be executed (with + `dispatch-event') and discarded. This function is provided as a + convenience; it is equivalent to the Lisp code + + (while (progn + (next-event event) + (not (or (key-press-event-p event) + (button-press-event-p event) + (button-release-event-p event) + (menu-event-p event)))) + (dispatch-event event)) + + Here is what happens if you call `next-command-event' and then + press the right-arrow function key: + + (next-command-event) + => # + + - Function: read-char + This function reads and returns a character of command input. If a + mouse click is detected, an error is signalled. The character + typed is returned as an ASCII value. This function is retained for + compatibility with Emacs 18, and is most likely the wrong thing + for you to be using: consider using `next-command-event' instead. + + - Function: enqueue-eval-event function object + This function adds an eval event to the back of the queue. The + eval event will be the next event read after all pending events. + + +File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input + +Dispatching an Event +-------------------- + + - Function: dispatch-event event + Given an event object returned by `next-event', this function + executes it. This is the basic function that makes XEmacs respond + to user input; it also deals with notifications from the window + system (such as Expose events). + + +File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input + +Quoted Character Input +---------------------- + + You can use the function `read-quoted-char' to ask the user to +specify a character, and allow the user to specify a control or meta +character conveniently, either literally or as an octal character code. +The command `quoted-insert' uses this function. + + - Function: read-quoted-char &optional prompt + This function is like `read-char', except that if the first + character read is an octal digit (0-7), it reads up to two more + octal digits (but stopping if a non-octal digit is found) and + returns the character represented by those digits in octal. + + Quitting is suppressed when the first character is read, so that + the user can enter a `C-g'. *Note Quitting::. + + If PROMPT is supplied, it specifies a string for prompting the + user. The prompt string is always displayed in the echo area, + followed by a single `-'. + + In the following example, the user types in the octal number 177 + (which is 127 in decimal). + + (read-quoted-char "What character") + + ---------- Echo Area ---------- + What character-177 + ---------- Echo Area ---------- + + => 127 + + +File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input + +Miscellaneous Event Input Features +---------------------------------- + + This section describes how to "peek ahead" at events without using +them up, how to check for pending input, and how to discard pending +input. + + See also the variables `last-command-event' and `last-command-char' +(*Note Command Loop Info::). + + - Variable: unread-command-events + This variable holds a list of events waiting to be read as command + input. The events are used in the order they appear in the list, + and removed one by one as they are used. + + The variable is needed because in some cases a function reads a + event and then decides not to use it. Storing the event in this + variable causes it to be processed normally, by the command loop + or by the functions to read command input. + + For example, the function that implements numeric prefix arguments + reads any number of digits. When it finds a non-digit event, it + must unread the event so that it can be read normally by the + command loop. Likewise, incremental search uses this feature to + unread events with no special meaning in a search, because these + events should exit the search and then execute normally. + + + - Variable: unread-command-event + This variable holds a single event to be read as command input. + + This variable is mostly obsolete now that you can use + `unread-command-events' instead; it exists only to support programs + written for versions of XEmacs prior to 19.12. + + - Function: input-pending-p + This function determines whether any command input is currently + available to be read. It returns immediately, with value `t' if + there is available input, `nil' otherwise. On rare occasions it + may return `t' when no input is available. + + - Variable: last-input-event + This variable is set to the last keyboard or mouse button event + received. + + This variable is off limits: you may not set its value or modify + the event that is its value, as it is destructively modified by + `read-key-sequence'. If you want to keep a pointer to this value, + you must use `copy-event'. + + Note that this variable is an alias for `last-input-char' in FSF + Emacs. + + In the example below, a character is read (the character `1'). It + becomes the value of `last-input-event', while `C-e' (from the + `C-x C-e' command used to evaluate this expression) remains the + value of `last-command-event'. + + (progn (print (next-command-event)) + (print last-command-event) + last-input-event) + -| # + -| # + => # + + - Variable: last-input-char + If the value of `last-input-event' is a keyboard event, then this + is the nearest ASCII equivalent to it. Remember that there is + _not_ a 1:1 mapping between keyboard events and ASCII characters: + the set of keyboard events is much larger, so writing code that + examines this variable to determine what key has been typed is bad + practice, unless you are certain that it will be one of a small + set of characters. + + This function exists for compatibility with Emacs version 18. + + - Function: discard-input + This function discards the contents of the terminal input buffer + and cancels any keyboard macro that might be in the process of + definition. It returns `nil'. + + In the following example, the user may type a number of characters + right after starting the evaluation of the form. After the + `sleep-for' finishes sleeping, `discard-input' discards any + characters typed during the sleep. + + (progn (sleep-for 2) + (discard-input)) + => nil + + +File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop + +Waiting for Elapsed Time or Input +================================= + + The wait functions are designed to wait for a certain amount of time +to pass or until there is input. For example, you may wish to pause in +the middle of a computation to allow the user time to view the display. +`sit-for' pauses and updates the screen, and returns immediately if +input comes in, while `sleep-for' pauses without updating the screen. + + Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take +two arguments to specify the time (one integer and one float value), +instead of a single argument that can be either an integer or a float. + + - Function: sit-for seconds &optional nodisplay + This function performs redisplay (provided there is no pending + input from the user), then waits SECONDS seconds, or until input is + available. The result is `t' if `sit-for' waited the full time + with no input arriving (see `input-pending-p' in *Note Peeking and + Discarding::). Otherwise, the value is `nil'. + + The argument SECONDS need not be an integer. If it is a floating + point number, `sit-for' waits for a fractional number of seconds. + + Redisplay is normally preempted if input arrives, and does not + happen at all if input is available before it starts. (You can + force screen updating in such a case by using `force-redisplay'. + *Note Refresh Screen::.) If there is no input pending, you can + force an update with no delay by using `(sit-for 0)'. + + If NODISPLAY is non-`nil', then `sit-for' does not redisplay, but + it still returns as soon as input is available (or when the + timeout elapses). + + The usual purpose of `sit-for' is to give the user time to read + text that you display. + + - Function: sleep-for seconds + This function simply pauses for SECONDS seconds without updating + the display. This function pays no attention to available input. + It returns `nil'. + + The argument SECONDS need not be an integer. If it is a floating + point number, `sleep-for' waits for a fractional number of seconds. + + Use `sleep-for' when you wish to guarantee a delay. + + *Note Time of Day::, for functions to get the current time. + + File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop Quitting @@ -69,7 +483,7 @@ effect is to cancel the prefix key as well as any prefix argument. In the minibuffer, `C-g' has a different definition: it aborts out of the minibuffer. This means, in effect, that it exits the minibuffer and then quits. (Simply quitting would return to the command loop -*within* the minibuffer.) The reason why `C-g' does not quit directly +_within_ the minibuffer.) The reason why `C-g' does not quit directly when the command reader is reading input is so that its meaning can be redefined in the minibuffer in this way. `C-g' following a prefix key is not redefined in the minibuffer, and it has its normal effect of @@ -225,41 +639,41 @@ argument, either numeric or raw, in the `interactive' declaration. value of the prefix argument directly in the variable `current-prefix-arg', but this is less clean. - - Function: prefix-numeric-value ARG + - Function: prefix-numeric-value raw This function returns the numeric meaning of a valid raw prefix - argument value, ARG. The argument may be a symbol, a number, or a + argument value, RAW. The argument may be a symbol, a number, or a list. If it is `nil', the value 1 is returned; if it is `-', the value -1 is returned; if it is a number, that number is returned; if it is a list, the CAR of that list (which should be a number) is returned. - Variable: current-prefix-arg - This variable holds the raw prefix argument for the *current* + This variable holds the raw prefix argument for the _current_ command. Commands may examine it directly, but the usual way to access it is with `(interactive "P")'. - Variable: prefix-arg The value of this variable is the raw prefix argument for the - *next* editing command. Commands that specify prefix arguments for + _next_ editing command. Commands that specify prefix arguments for the following command work by setting this variable. Do not call the functions `universal-argument', `digit-argument', or `negative-argument' unless you intend to let the user enter the prefix -argument for the *next* command. +argument for the _next_ command. - Command: universal-argument This command reads input and specifies a prefix argument for the following command. Don't call this command yourself unless you know what you are doing. - - Command: digit-argument ARG + - Command: digit-argument arg This command adds to the prefix argument for the following command. The argument ARG is the raw prefix argument as it was before this command; it is used to compute the updated prefix argument. Don't call this command yourself unless you know what you are doing. - - Command: negative-argument ARG + - Command: negative-argument arg This command adds to the numeric argument for the next command. The argument ARG is the raw prefix argument as it was before this command; its value is negated to form the new prefix argument. @@ -302,7 +716,7 @@ commands. `recursive-edit'. This function contains the command loop; it also contains a call to `catch' with tag `exit', which makes it possible to exit the recursive editing level by throwing to `exit' (*note Catch and -Throw::.). If you throw a value other than `t', then `recursive-edit' +Throw::). If you throw a value other than `t', then `recursive-edit' returns normally to the function that called it. The command `C-M-c' (`exit-recursive-edit') does this. Throwing a `t' value causes `recursive-edit' to quit, so that control returns to the command loop @@ -327,7 +741,7 @@ recursive edit but also provides the other features of the debugger. Recursive editing levels are also used when you type `C-r' in `query-replace' or use `C-x q' (`kbd-macro-query'). - - Function: recursive-edit + - Command: recursive-edit This function invokes the editor command loop. It is called automatically by the initialization of XEmacs, to let the user begin editing. When called from a Lisp program, it enters a @@ -399,12 +813,12 @@ saying the command is disabled includes that string. For example: when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs. - - Command: enable-command COMMAND + - Command: enable-command command Allow COMMAND to be executed without special confirmation from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions. - - Command: disable-command COMMAND + - Command: disable-command command Require special confirmation to execute COMMAND from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions. @@ -439,7 +853,7 @@ considered complex. represented as a form to evaluate. It continues to accumulate all complex commands for the duration of the editing session, but all but the first (most recent) thirty elements are deleted when a - garbage collection takes place (*note Garbage Collection::.). + garbage collection takes place (*note Garbage Collection::). command-history => ((switch-to-buffer "chistory.texi") @@ -448,7 +862,7 @@ considered complex. (find-tag "repeat-complex-command")) This history list is actually a special case of minibuffer history -(*note Minibuffer History::.), with one special twist: the elements are +(*note Minibuffer History::), with one special twist: the elements are expressions rather than strings. There are a number of commands devoted to the editing and recall of @@ -467,12 +881,12 @@ Keyboard Macros considered a command and made the definition of a key. The Lisp representation of a keyboard macro is a string or vector containing the events. Don't confuse keyboard macros with Lisp macros (*note -Macros::.). +Macros::). - - Function: execute-kbd-macro MACRO &optional COUNT + - Function: execute-kbd-macro macro &optional count This function executes MACRO as a sequence of events. If MACRO is a string or vector, then the events in it are executed exactly as - if they had been input by the user. The sequence is *not* + if they had been input by the user. The sequence is _not_ expected to be a single key sequence; normally a keyboard macro definition consists of several key sequences concatenated. @@ -549,7 +963,7 @@ be any Lisp objects, though only certain types are meaningful for execution by the command loop). Given an event (or an event type) and a keymap, XEmacs can get the event's definition. Events mapped in keymaps include keypresses, button presses, and button releases (*note -Events::.). +Events::). A sequence of input events that form a unit is called a "key sequence", or "key" for short. A sequence of one event is always a key @@ -604,7 +1018,7 @@ Format of Keymaps bindings. Note that this is different from Emacs 18 and FSF Emacs, where keymaps are lists. - - Function: keymapp OBJECT + - Function: keymapp object This function returns `t' if OBJECT is a keymap, `nil' otherwise.  @@ -615,7 +1029,7 @@ Creating Keymaps Here we describe the functions for creating keymaps. - - Function: make-keymap &optional NAME + - Function: make-keymap &optional name This function constructs and returns a new keymap object. All entries in it are `nil', meaning "command undefined". @@ -623,28 +1037,28 @@ Creating Keymaps as in `set-keymap-name'. This name is only a debugging convenience; it is not used except when printing the keymap. - - Function: make-sparse-keymap &optional NAME + - Function: make-sparse-keymap &optional name This function constructs and returns a new keymap object. All entries in it are `nil', meaning "command undefined". The only difference between this function and `make-keymap' is that this function returns a "smaller" keymap (one that is expected to - contain fewer entries). As keymaps dynamically resize, the + contain fewer entries). As keymaps dynamically resize, this distinction is not great. Optional argument NAME specifies a name to assign to the keymap, as in `set-keymap-name'. This name is only a debugging convenience; it is not used except when printing the keymap. - - Function: set-keymap-name KEYMAP NEW-NAME + - Function: set-keymap-name keymap new-name This function assigns a "name" to a keymap. The name is only a debugging convenience; it is not used except when printing the keymap. - - Function: keymap-name KEYMAP + - Function: keymap-name keymap This function returns the "name" of a keymap, as assigned using `set-keymap-name'. - - Function: copy-keymap KEYMAP + - Function: copy-keymap keymap This function returns a copy of KEYMAP. Any keymaps that appear directly as bindings in KEYMAP are also copied recursively, and so on to any number of levels. However, recursive copying does not @@ -678,7 +1092,7 @@ depth-first search of all the ancestors of the keymap is conducted. `(current-global-map)' is the default parent of all keymaps. - - Function: set-keymap-parents KEYMAP PARENTS + - Function: set-keymap-parents keymap parents This function sets the parent keymaps of KEYMAP to the list PARENTS. @@ -689,7 +1103,7 @@ depth-first search of all the ancestors of the keymap is conducted. `define-key' to change KEYMAP, that affects the bindings in that map, but has no effect on any of the keymaps in PARENTS. - - Function: keymap-parents KEYMAP + - Function: keymap-parents keymap This function returns the list of parent keymaps of KEYMAP, or `nil' if KEYMAP has no parents. @@ -701,416 +1115,11 @@ format. Note that if you specify a default binding for a keymap, neither the keymap's parents nor the current global map are searched for key bindings. - - Function: set-keymap-default-binding KEYMAP COMMAND + - Function: set-keymap-default-binding keymap command This function sets the default binding of KEYMAP to COMMAND, or `nil' if no default is desired. - - Function: keymap-default-binding KEYMAP + - Function: keymap-default-binding keymap This function returns the default binding of KEYMAP, or `nil' if it has none. - -File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps - -Key Sequences -============= - - Contrary to popular belief, the world is not ASCII. When running -under a window manager, XEmacs can tell the difference between, for -example, the keystrokes `control-h', `control-shift-h', and -`backspace'. You can, in fact, bind different commands to each of -these. - - A "key sequence" is a set of keystrokes. A "keystroke" is a keysym -and some set of modifiers (such as and ). A "keysym" -is what is printed on the keys on your keyboard. - - A keysym may be represented by a symbol, or (if and only if it is -equivalent to an ASCII character in the range 32 - 255) by a character -or its equivalent ASCII code. The `A' key may be represented by the -symbol `A', the character `?A', or by the number 65. The `break' key -may be represented only by the symbol `break'. - - A keystroke may be represented by a list: the last element of the -list is the key (a symbol, character, or number, as above) and the -preceding elements are the symbolic names of modifier keys (, -, , , , and ). Thus, the sequence -`control-b' is represented by the forms `(control b)', `(control ?b)', -and `(control 98)'. A keystroke may also be represented by an event -object, as returned by the `next-command-event' and `read-key-sequence' -functions. - - Note that in this context, the keystroke `control-b' is *not* -represented by the number 2 (the ASCII code for `^B') or the character -`?\^B'. See below. - - The modifier is somewhat of a special case. You should not -(and cannot) use `(meta shift a)' to mean `(meta A)', since for -characters that have ASCII equivalents, the state of the shift key is -implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)' -to mean `+', as that sort of thing varies from keyboard to keyboard. -The modifier is for use only with characters that do not have a -second keysym on the same key, such as `backspace' and `tab'. - - A key sequence is a vector of keystrokes. As a degenerate case, -elements of this vector may also be keysyms if they have no modifiers. -That is, the `A' keystroke is represented by all of these forms: - - A ?A 65 (A) (?A) (65) - [A] [?A] [65] [(A)] [(?A)] [(65)] - - the `control-a' keystroke is represented by these forms: - - (control A) (control ?A) (control 65) - [(control A)] [(control ?A)] [(control 65)] - - the key sequence `control-c control-a' is represented by these forms: - - [(control c) (control a)] [(control ?c) (control ?a)] - [(control 99) (control 65)] etc. - - Mouse button clicks work just like keypresses: `(control button1)' -means pressing the left mouse button while holding down the control -key. `[(control c) (shift button3)]' means `control-c', hold , -click right. - - Commands may be bound to the mouse-button up-stroke rather than the -down-stroke as well. `button1' means the down-stroke, and `button1up' -means the up-stroke. Different commands may be bound to the up and -down strokes, though that is probably not what you want, so be careful. - - For backward compatibility, a key sequence may also be represented by -a string. In this case, it represents the key sequence(s) that would -produce that sequence of ASCII characters in a purely ASCII world. For -example, a string containing the ASCII backspace character, `"\^H"', -would represent two key sequences: `(control h)' and `backspace'. -Binding a command to this will actually bind both of those key -sequences. Likewise for the following pairs: - - control h backspace - control i tab - control m return - control j linefeed - control [ escape - control @ control space - - After binding a command to two key sequences with a form like - - (define-key global-map "\^X\^I" 'command-1) - -it is possible to redefine only one of those sequences like so: - - (define-key global-map [(control x) (control i)] 'command-2) - (define-key global-map [(control x) tab] 'command-3) - - Of course, all of this applies only when running under a window -system. If you're talking to XEmacs through a TTY connection, you -don't get any of these features. - - - Function: event-matches-key-specifier-p EVENT KEY-SPECIFIER - This function returns non-`nil' if EVENT matches KEY-SPECIFIER, - which can be any valid form representing a key sequence. This can - be useful, e.g., to determine if the user pressed `help-char' or - `quit-char'. - - -File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps - -Prefix Keys -=========== - - A "prefix key" has an associated keymap that defines what to do with -key sequences that start with the prefix key. For example, `C-x' is a -prefix key, and it uses a keymap that is also stored in the variable -`ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and -their keymaps: - - * `help-map' is used for events that follow `C-h'. - - * `mode-specific-map' is for events that follow `C-c'. This map is - not actually mode specific; its name was chosen to be informative - for the user in `C-h b' (`display-bindings'), where it describes - the main use of the `C-c' prefix key. - - * `ctl-x-map' is the map used for events that follow `C-x'. This - map is also the function definition of `Control-X-prefix'. - - * `ctl-x-4-map' is used for events that follow `C-x 4'. - - * `ctl-x-5-map' is used for events that follow `C-x 5'. - - * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have - no special name. - - * `esc-map' is an evil hack that is present for compatibility - purposes with Emacs 18. Defining a key in `esc-map' is equivalent - to defining the same key in `global-map' but with the - prefix added. You should *not* use this in your code. (This map is - also the function definition of `ESC-prefix'.) - - The binding of a prefix key is the keymap to use for looking up the -events that follow the prefix key. (It may instead be a symbol whose -function definition is a keymap. The effect is the same, but the symbol -serves as a name for the prefix key.) Thus, the binding of `C-x' is -the symbol `Control-X-prefix', whose function definition is the keymap -for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.) - - Prefix key definitions can appear in any active keymap. The -definitions of `C-c', `C-x', `C-h' and as prefix keys appear in -the global map, so these prefix keys are always available. Major and -minor modes can redefine a key as a prefix by putting a prefix key -definition for it in the local map or the minor mode's map. *Note -Active Keymaps::. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make `C-p' a prefix key in the local -keymap, in such a way that `C-p' is identical to `C-x'. Then the -binding for `C-p C-f' is the function `find-file', just like `C-x C-f'. -The key sequence `C-p 6' is not found in any active keymap. - - (use-local-map (make-sparse-keymap)) - => nil - (local-set-key "\C-p" ctl-x-map) - => nil - (key-binding "\C-p\C-f") - => find-file - - (key-binding "\C-p6") - => nil - - - Function: define-prefix-command SYMBOL &optional MAPVAR - This function defines SYMBOL as a prefix command: it creates a - keymap and stores it as SYMBOL's function definition. Storing the - symbol as the binding of a key makes the key a prefix key that has - a name. If optional argument MAPVAR is not specified, it also - sets SYMBOL as a variable, to have the keymap as its value. (If - MAPVAR is given and is not `t', its value is stored as the value - of SYMBOL.) The function returns SYMBOL. - - In Emacs version 18, only the function definition of SYMBOL was - set, not the value as a variable. - - -File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps - -Active Keymaps -============== - - XEmacs normally contains many keymaps; at any given time, just a few -of them are "active" in that they participate in the interpretation of -user input. These are the global keymap, the current buffer's local -keymap, and the keymaps of any enabled minor modes. - - The "global keymap" holds the bindings of keys that are defined -regardless of the current buffer, such as `C-f'. The variable -`global-map' holds this keymap, which is always active. - - Each buffer may have another keymap, its "local keymap", which may -contain new or overriding definitions for keys. The current buffer's -local keymap is always active except when `overriding-local-map' or -`overriding-terminal-local-map' overrides it. Extents and text -properties can specify an alternative local map for certain parts of the -buffer; see *Note Extents and Events::. - - Each minor mode may have a keymap; if it does, the keymap is active -when the minor mode is enabled. - - The variable `overriding-local-map' and -`overriding-terminal-local-map', if non-`nil', specify other local -keymaps that override the buffer's local map and all the minor mode -keymaps. - - All the active keymaps are used together to determine what command to -execute when a key is entered. XEmacs searches these maps one by one, -in order of decreasing precedence, until it finds a binding in one of -the maps. - - More specifically: - - For key-presses, the order of keymaps searched is: - - * the `keymap' property of any extent(s) or text properties at point; - - * any applicable minor-mode maps; - - * the current local map of the current buffer; - - * the current global map. - - For mouse-clicks, the order of keymaps searched is: - - * the current local map of the `mouse-grabbed-buffer' if any; - - * the `keymap' property of any extent(s) at the position of the click - (this includes modeline extents); - - * the `modeline-map' of the buffer corresponding to the modeline - under the mouse (if the click happened over a modeline); - - * the value of `toolbar-map' in the current buffer (if the click - happened over a toolbar); - - * the current local map of the buffer under the mouse (does not - apply to toolbar clicks); - - * any applicable minor-mode maps; - - * the current global map. - - Note that if `overriding-local-map' or -`overriding-terminal-local-map' is non-`nil', *only* those two maps and -the current global map are searched. - - The procedure for searching a single keymap is called "key lookup"; -see *Note Key Lookup::. - - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using `local-set-key', for -example) is seen also in the other buffers that share that keymap. - - The local keymaps that are used for Lisp mode, C mode, and several -other major modes exist even if they have not yet been used. These -local maps are the values of the variables `lisp-mode-map', -`c-mode-map', and so on. For most other modes, which are less -frequently used, the local keymap is constructed only when the mode is -used for the first time in a session. - - The minibuffer has local keymaps, too; they contain various -completion and exit commands. *Note Intro to Minibuffers::. - - *Note Standard Keymaps::, for a list of standard keymaps. - - - Function: current-keymaps &optional EVENT-OR-KEYS - This function returns a list of the current keymaps that will be - searched for bindings. This lists keymaps such as the current - local map and the minor-mode maps, but does not list the parents - of those keymaps. EVENT-OR-KEYS controls which keymaps will be - listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last - element is a mouse event), the keymaps for that mouse event will - be listed. Otherwise, the keymaps for key presses will be listed. - - - Variable: global-map - This variable contains the default global keymap that maps XEmacs - keyboard input to commands. The global keymap is normally this - keymap. The default global keymap is a full keymap that binds - `self-insert-command' to all of the printing characters. - - It is normal practice to change the bindings in the global map, - but you should not assign this variable any value other than the - keymap it starts out with. - - - Function: current-global-map - This function returns the current global keymap. This is the same - as the value of `global-map' unless you change one or the other. - - (current-global-map) - => # - - - Function: current-local-map - This function returns the current buffer's local keymap, or `nil' - if it has none. In the following example, the keymap for the - `*scratch*' buffer (using Lisp Interaction mode) has a number of - entries, including one prefix key, `C-x'. - - (current-local-map) - => # - (describe-bindings-internal (current-local-map)) - => ; Inserted into the buffer: - backspace backward-delete-char-untabify - linefeed eval-print-last-sexp - delete delete-char - C-j eval-print-last-sexp - C-x << Prefix Command >> - M-tab lisp-complete-symbol - M-; lisp-indent-for-comment - M-C-i lisp-complete-symbol - M-C-q indent-sexp - M-C-x eval-defun - Alt-backspace backward-kill-sexp - Alt-delete kill-sexp - - C-x x edebug-defun - - - Function: current-minor-mode-maps - This function returns a list of the keymaps of currently enabled - minor modes. - - - Function: use-global-map KEYMAP - This function makes KEYMAP the new current global keymap. It - returns `nil'. - - It is very unusual to change the global keymap. - - - Function: use-local-map KEYMAP &optional BUFFER - This function makes KEYMAP the new local keymap of BUFFER. BUFFER - defaults to the current buffer. If KEYMAP is `nil', then the - buffer has no local keymap. `use-local-map' returns `nil'. Most - major mode commands use this function. - - - Variable: minor-mode-map-alist - This variable is an alist describing keymaps that may or may not be - active according to the values of certain variables. Its elements - look like this: - - (VARIABLE . KEYMAP) - - The keymap KEYMAP is active whenever VARIABLE has a non-`nil' - value. Typically VARIABLE is the variable that enables or - disables a minor mode. *Note Keymaps and Minor Modes::. - - Note that elements of `minor-mode-map-alist' do not have the same - structure as elements of `minor-mode-alist'. The map must be the - CDR of the element; a list with the map as the second element will - not do. - - What's more, the keymap itself must appear in the CDR. It does not - work to store a variable in the CDR and make the map the value of - that variable. - - When more than one minor mode keymap is active, their order of - priority is the order of `minor-mode-map-alist'. But you should - design minor modes so that they don't interfere with each other. - If you do this properly, the order will not matter. - - See also `minor-mode-key-binding', above. See *Note Keymaps and - Minor Modes::, for more information about minor modes. - - - Variable: modeline-map - This variable holds the keymap consulted for mouse-clicks on the - modeline of a window. This variable may be buffer-local; its - value will be looked up in the buffer of the window whose modeline - was clicked upon. - - - Variable: toolbar-map - This variable holds the keymap consulted for mouse-clicks over a - toolbar. - - - Variable: mouse-grabbed-buffer - If non-`nil', a buffer which should be consulted first for all - mouse activity. When a mouse-click is processed, it will first be - looked up in the local-map of this buffer, and then through the - normal mechanism if there is no binding for that click. This - buffer's value of `mode-motion-hook' will be consulted instead of - the `mode-motion-hook' of the buffer of the window under the mouse. - You should *bind* this, not set it. - - - Variable: overriding-local-map - If non-`nil', this variable holds a keymap to use instead of the - buffer's local keymap and instead of all the minor mode keymaps. - This keymap, if any, overrides all other maps that would have been - active, except for the current global map. - - - Variable: overriding-terminal-local-map - If non-`nil', this variable holds a keymap to use instead of the - buffer's local keymap and instead of all the minor mode keymaps, - but for the selected console only. (In other words, this variable - is always console-local; putting a keymap here only applies to - keystrokes coming from the selected console. *Note Consoles and - Devices::.) This keymap, if any, overrides all other maps that - would have been active, except for the current global map. -