X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Flispref%2Fkeymaps.texi;h=d082258a050c7d3b1a0786b0003295249e6dd64a;hb=930837f0e2867be99a167b32f57d57898c838571;hp=3fd15ff7c7844ada3b0c238e19ebf578fe001fb5;hpb=6883ee56ec887c2c48abe5b06b5e66aa74031910;p=chise%2Fxemacs-chise.git- diff --git a/man/lispref/keymaps.texi b/man/lispref/keymaps.texi index 3fd15ff..d082258 100644 --- a/man/lispref/keymaps.texi +++ b/man/lispref/keymaps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the XEmacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c Copyright (C) 1996 Ben Wing. @c See the file lispref.texi for copying conditions. @setfilename ../../info/keymaps.info @@ -131,7 +131,7 @@ This function constructs and returns a new keymap object. All entries in it are @code{nil}, meaning ``command undefined''. The only difference between this function and @code{make-keymap} is that this function returns a ``smaller'' keymap (one that is expected to contain -fewer entries). As keymaps dynamically resize, the distinction is not +fewer entries). As keymaps dynamically resize, this distinction is not great. Optional argument @var{name} specifies a name to assign to the keymap, @@ -235,7 +235,7 @@ if it has none. @section Key Sequences @cindex key sequences - Contrary to popular belief, the world is not @sc{ASCII}. When running + Contrary to popular belief, the world is not @sc{ascii}. When running under a window manager, XEmacs can tell the difference between, for example, the keystrokes @kbd{control-h}, @kbd{control-shift-h}, and @kbd{backspace}. You can, in fact, bind different commands to each of @@ -246,8 +246,8 @@ keysym and some set of modifiers (such as @key{CONTROL} and @key{META}). A @dfn{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 @sc{ASCII} character in the range 32 - 255) by a -character or its equivalent @sc{ASCII} code. The @kbd{A} key may be +equivalent to an @sc{ascii} character in the range 32 - 255) by a +character or its equivalent @sc{ascii} code. The @kbd{A} key may be represented by the symbol @code{A}, the character @code{?A}, or by the number 65. The @kbd{break} key may be represented only by the symbol @code{break}. @@ -262,12 +262,12 @@ keystroke may also be represented by an event object, as returned by the @code{next-command-event} and @code{read-key-sequence} functions. Note that in this context, the keystroke @kbd{control-b} is @emph{not} -represented by the number 2 (the @sc{ASCII} code for @samp{^B}) or the +represented by the number 2 (the @sc{ascii} code for @samp{^B}) or the character @code{?\^B}. See below. The @key{SHIFT} modifier is somewhat of a special case. You should not (and cannot) use @code{(meta shift a)} to mean @code{(meta A)}, -since for characters that have @sc{ASCII} equivalents, the state of the +since for characters that have @sc{ascii} equivalents, the state of the shift key is implicit in the keysym (@samp{a} vs. @samp{A}). You also cannot say @code{(shift =)} to mean @code{+}, as that sort of thing varies from keyboard to keyboard. The @key{SHIFT} modifier is for use @@ -279,23 +279,23 @@ elements of this vector may also be keysyms if they have no modifiers. That is, the @kbd{A} keystroke is represented by all of these forms: @example - A ?A 65 (A) (?A) (65) - [A] [?A] [65] [(A)] [(?A)] [(65)] + A ?A 65 (A) (?A) (65) + [A] [?A] [65] [(A)] [(?A)] [(65)] @end example - + the @kbd{control-a} keystroke is represented by these forms: @example - (control A) (control ?A) (control 65) - [(control A)] [(control ?A)] [(control 65)] + (control A) (control ?A) (control 65) + [(control A)] [(control ?A)] [(control 65)] @end example the key sequence @kbd{control-c control-a} is represented by these forms: @example - [(control c) (control a)] [(control ?c) (control ?a)] - [(control 99) (control 65)] etc. + [(control c) (control a)] [(control ?c) (control ?a)] + [(control 99) (control 65)] etc. @end example Mouse button clicks work just like keypresses: @code{(control @@ -311,38 +311,38 @@ 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 @sc{ASCII} characters in a purely @sc{ASCII} -world. For example, a string containing the @sc{ASCII} backspace +produce that sequence of @sc{ascii} characters in a purely @sc{ascii} +world. For example, a string containing the @sc{ascii} backspace character, @code{"\^H"}, would represent two key sequences: @code{(control h)} and @code{backspace}. Binding a command to this will actually bind both of those key sequences. Likewise for the following pairs: @example - control h backspace - control i tab - control m return - control j linefeed - control [ escape - control @@ control space + control h backspace + control i tab + control m return + control j linefeed + control [ escape + control @@ control space @end example After binding a command to two key sequences with a form like @example - (define-key global-map "\^X\^I" 'command-1) + (define-key global-map "\^X\^I" 'command-1) @end example @noindent it is possible to redefine only one of those sequences like so: @example - (define-key global-map [(control x) (control i)] 'command-2) - (define-key global-map [(control x) tab] 'command-3) + (define-key global-map [(control x) (control i)] 'command-2) + (define-key global-map [(control x) tab] 'command-3) @end example Of course, all of this applies only when running under a window -system. If you're talking to XEmacs through a @sc{TTY} connection, you +system. If you're talking to XEmacs through a @sc{tty} connection, you don't get any of these features. @defun event-matches-key-specifier-p event key-specifier @@ -602,11 +602,13 @@ other. @end example @end defun -@defun current-local-map -This function returns the current buffer's local keymap, or @code{nil} -if it has none. In the following example, the keymap for the -@samp{*scratch*} buffer (using Lisp Interaction mode) has a number -of entries, including one prefix key, @kbd{C-x}. +@defun current-local-map &optional buffer +This function returns @var{buffer}'s local keymap, or @code{nil} +if it has none. @var{buffer} defaults to the current buffer. + +In the following example, the keymap for the @samp{*scratch*} buffer +(using Lisp Interaction mode) has a number of entries, including one +prefix key, @kbd{C-x}. @example @group @@ -614,22 +616,22 @@ of entries, including one prefix key, @kbd{C-x}. @result{} # (describe-bindings-internal (current-local-map)) @result{} ; @r{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 +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 @end group @group -C-x x edebug-defun +C-x x edebug-defun @end group @end example @end defun @@ -931,8 +933,8 @@ bindings, as in @code{lookup-key} (above). @end example @end defun -@defun local-key-binding key &optional accept-defaults -This function returns the binding for @var{key} in the current +@defun local-key-binding keys &optional accept-defaults +This function returns the binding for @var{keys} in the current local keymap, or @code{nil} if it is undefined there. @c Emacs 19 feature @@ -940,8 +942,8 @@ The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun -@defun global-key-binding key &optional accept-defaults -This function returns the binding for command @var{key} in the +@defun global-key-binding keys &optional accept-defaults +This function returns the binding for command @var{keys} in the current global keymap, or @code{nil} if it is undefined there. @c Emacs 19 feature @@ -973,14 +975,14 @@ This variable is the meta-prefix character code. It is used when translating a two-character sequence to a meta character so it can be looked up in a keymap. For useful results, the value should be a prefix event (@pxref{Prefix Keys}). The default value is @code{?\^[} (integer -27), which is the @sc{ASCII} character usually produced by the @key{ESC} +27), which is the @sc{ascii} character usually produced by the @key{ESC} key. As long as the value of @code{meta-prefix-char} remains @code{?\^[}, key lookup translates @kbd{@key{ESC} b} into @kbd{M-b}, which is normally defined as the @code{backward-word} command. However, if you set @code{meta-prefix-char} to @code{?\^X} (i.e. the keystroke -@kbd{C-x}) or its equivalent @sc{ASCII} code @code{24}, then XEmacs will +@kbd{C-x}) or its equivalent @sc{ascii} code @code{24}, then XEmacs will translate @kbd{C-x b} (whose standard binding is the @code{switch-to-buffer} command) into @kbd{M-b}. @@ -1002,7 +1004,7 @@ meta-prefix-char ; @r{The default value.} @end group @group (setq meta-prefix-char 24) - @result{} 24 + @result{} 24 @end group @group (key-binding "\C-xb") @@ -1149,26 +1151,28 @@ changing an entry in @code{ctl-x-map}, and this has the effect of changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the default global map. -@defun substitute-key-definition olddef newdef keymap &optional oldmap +@defun substitute-key-definition olddef newdef keymap &optional oldmap prefix @cindex replace bindings This function replaces @var{olddef} with @var{newdef} for any keys in @var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. +@var{olddef} is replaced with @var{newdef} wherever it appears. Prefix +keymaps are checked recursively. + +The function returns @code{nil}. For example, this redefines @kbd{C-x C-f}, if you do it in an XEmacs with standard bindings: @smallexample @group -(substitute-key-definition +(substitute-key-definition 'find-file 'find-file-read-only (current-global-map)) @end group @end smallexample @c Emacs 19 feature If @var{oldmap} is non-@code{nil}, then its bindings determine which -keys to rebind. The rebindings still happen in @var{newmap}, not in +keys to rebind. The rebindings still happen in @var{keymap}, not in @var{oldmap}. Thus, you can change one map under the control of the bindings in another. For example, @@ -1182,6 +1186,11 @@ bindings in another. For example, puts the special deletion command in @code{my-map} for whichever keys are globally bound to the standard deletion command. +If argument @var{prefix} is non-@code{nil}, then only those occurrences +of @var{olddef} found in keymaps accessible through the keymap bound to +@var{prefix} in @var{keymap} are redefined. See also +@code{accessible-keymaps}. + @ignore @c Emacs 18 only Prefix keymaps that appear within @var{keymap} are not checked @@ -1194,9 +1203,9 @@ Here is an example showing a keymap before and after substitution: @smallexample @group -(setq map '(keymap - (?1 . olddef-1) - (?2 . olddef-2) +(setq map '(keymap + (?1 . olddef-1) + (?2 . olddef-2) (?3 . olddef-1))) @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) @end group @@ -1225,8 +1234,8 @@ digits to run @code{digit-argument}, and @kbd{-} to run @code{negative-argument}. Otherwise it makes them undefined like the rest of the printing characters. -@cindex yank suppression -@cindex @code{quoted-insert} suppression +@cindex yank suppression +@cindex @code{quoted-insert} suppression The @code{suppress-keymap} function does not make it impossible to modify a buffer, as it does not suppress commands such as @code{yank} and @code{quoted-insert}. To prevent any modification of a buffer, make @@ -1404,7 +1413,7 @@ sequences beginning with @kbd{C-x}.) @smallexample @group -(current-local-map) +(current-local-map) @result{} # (accessible-keymaps (current-local-map)) @result{}(([] . #) @@ -1452,7 +1461,7 @@ indicating their relationship to their enclosing keymap. @end defun @defun map-keymap function keymap &optional sort-first -This function applies @var{function} to each element of @code{KEYMAP}. +This function applies @var{function} to each element of @var{keymap}. @var{function} will be called with two arguments: a key-description list, and the binding. The order in which the elements of the keymap are passed to the function is unspecified. If the function inserts new @@ -1482,14 +1491,14 @@ bound to @var{definition} in a set of keymaps. The argument @var{definition} can be any object; it is compared with all keymap entries using @code{eq}. -KEYMAPS can be either a keymap (meaning search in that keymap and the +@var{keymaps} can be either a keymap (meaning search in that keymap and the current global keymap) or a list of keymaps (meaning search in exactly -those keymaps and no others). If KEYMAPS is nil, search in the currently -applicable maps for EVENT-OR-KEYS. +those keymaps and no others). If @var{keymaps} is nil, search in the currently +applicable maps for @var{event-or-keys}. -If @var{keymap} is a keymap, then the maps searched are @var{keymap} and -the global keymap. If @var{keymap} is a list of keymaps, then the maps -searched are exactly those keymaps, and no others. If @var{keymap} is +If @var{keymaps} is a keymap, then the maps searched are @var{keymaps} and +the global keymap. If @var{keymaps} is a list of keymaps, then the maps +searched are exactly those keymaps, and no others. If @var{keymaps} is @code{nil}, then the maps used are the current active keymaps for @var{event-or-keys} (this is equivalent to specifying @code{(current-keymaps @var{event-or-keys})} as the argument to @@ -1503,7 +1512,7 @@ If @var{firstonly} is @code{non-ascii}, then the value is a single string representing the first key sequence found, rather than a list of all possible key sequences. If @var{firstonly} is @code{t}, then the value is the first key sequence, except that key sequences consisting -entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII} +entirely of @sc{ascii} characters (or meta variants of @sc{ascii} characters) are preferred to all other key sequences. @end ignore @@ -1511,8 +1520,8 @@ If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't follow indirect keymap bindings. This makes it possible to search for an indirect definition itself. -This function is used by @code{where-is} (@pxref{Help, , Help, emacs, -The XEmacs Reference Manual}). +This function is used by @code{where-is} (@pxref{Help, , Help, xemacs, +The XEmacs Lisp Reference Manual}). @smallexample @group @@ -1538,26 +1547,28 @@ for mouse clicks. @code{describe-bindings-internal} is used to implement the help command @code{describe-bindings}. -@deffn Command describe-bindings prefix mouse-only-p +@deffn Command describe-bindings &optional prefix mouse-only-p This function creates a listing of all defined keys and their definitions. It writes the listing in a buffer named @samp{*Help*} and displays it in a window. -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. +If optional argument @var{prefix} is non-@code{nil}, it should be a +prefix key; then the listing includes only keys that start with +@var{prefix}. -When several characters with consecutive @sc{ASCII} codes have the +When several characters with consecutive @sc{ascii} codes have the same definition, they are shown together, as @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @sc{ASCII} codes to understand which characters this means. +know the @sc{ascii} codes to understand which characters this means. For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32, -@kbd{~} is @sc{ASCII} 126, and the characters between them include all +..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32, +@kbd{~} is @sc{ascii} 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.@:); all these characters are bound to @code{self-insert-command}. -If the second argument (prefix arg, interactively) is non-@code{nil} -then only the mouse bindings are displayed. +If the second optional argument @var{mouse-only-p} (prefix arg, +interactively) is non-@code{nil} then only the mouse bindings are +displayed. @end deffn @node Other Keymap Functions