Mercurial > emacs
comparison lispref/keymaps.texi @ 83466:9bec09743395
Merged from
Patches applied:
* emacs@sv.gnu.org/emacs--devo--0--patch-38
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-39
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-40
Update from CVS
git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-506
author | Karoly Lorentey <lorentey@elte.hu> |
---|---|
date | Fri, 03 Feb 2006 15:24:23 +0000 |
parents | 72c2736c8ab3 |
children | 067115a6e738 d6f8fe3307c8 |
comparison
equal
deleted
inserted
replaced
83465:3ec9cf0f2305 | 83466:9bec09743395 |
---|---|
20 * Format of Keymaps:: What a keymap looks like as a Lisp object. | 20 * Format of Keymaps:: What a keymap looks like as a Lisp object. |
21 * Creating Keymaps:: Functions to create and copy keymaps. | 21 * Creating Keymaps:: Functions to create and copy keymaps. |
22 * Inheritance and Keymaps:: How one keymap can inherit the bindings | 22 * Inheritance and Keymaps:: How one keymap can inherit the bindings |
23 of another keymap. | 23 of another keymap. |
24 * Prefix Keys:: Defining a key with a keymap as its definition. | 24 * Prefix Keys:: Defining a key with a keymap as its definition. |
25 * Active Keymaps:: Each buffer has a local keymap | 25 * Active Keymaps:: How Emacs searches the active keymaps |
26 for a key binding. | |
27 * Searching Keymaps:: A pseudo-Lisp summary of searching active maps. | |
28 * Controlling Active Maps:: Each buffer has a local keymap | |
26 to override the standard (global) bindings. | 29 to override the standard (global) bindings. |
27 A minor mode can also override them. | 30 A minor mode can also override them. |
28 * Key Lookup:: How extracting elements from keymaps works. | 31 * Key Lookup:: Finding a key's binding in one keymap. |
29 * Functions for Key Lookup:: How to request key lookup. | 32 * Functions for Key Lookup:: How to request key lookup. |
30 * Changing Key Bindings:: Redefining a key in a keymap. | 33 * Changing Key Bindings:: Redefining a key in a keymap. |
31 * Remapping Commands:: Bindings that translate one command to another. | 34 * Remapping Commands:: Bindings that translate one command to another. |
32 * Key Binding Commands:: Interactive interfaces for redefining keys. | 35 * Key Binding Commands:: Interactive interfaces for redefining keys. |
33 * Scanning Keymaps:: Looking through all keymaps, for printing help. | 36 * Scanning Keymaps:: Looking through all keymaps, for printing help. |
535 @cindex active keymap | 538 @cindex active keymap |
536 @cindex global keymap | 539 @cindex global keymap |
537 @cindex local keymap | 540 @cindex local keymap |
538 | 541 |
539 Emacs normally contains many keymaps; at any given time, just a few | 542 Emacs normally contains many keymaps; at any given time, just a few |
540 of them are @dfn{active} in that they participate in the | 543 of them are @dfn{active}, meaning that they participate in the |
541 interpretation of user input. All the active keymaps are used | 544 interpretation of user input. All the active keymaps are used |
542 together to determine what command to execute when a key is entered. | 545 together to determine what command to execute when a key is entered. |
543 Emacs searches these keymaps one by one, in a standard order, until it | 546 Emacs searches these keymaps one by one, in a standard order, until it |
544 finds a binding in one of the keymaps. (Searching a single keymap for a | 547 finds a binding in one of the keymaps. |
545 binding is called @dfn{key lookup}; see @ref{Key Lookup}.) | |
546 | 548 |
547 Normally the active keymaps are the @code{keymap} property keymap, | 549 Normally the active keymaps are the @code{keymap} property keymap, |
548 the keymaps of any enabled minor modes, the current buffer's local | 550 the keymaps of any enabled minor modes, the current buffer's local |
549 keymap, and the global keymap, in that order. Therefore, Emacs | 551 keymap, and the global keymap, in that order. Therefore, Emacs |
550 searches for each input key sequence in all these keymaps. | 552 searches for each input key sequence in all these keymaps. Here is a |
553 pseudo-Lisp description of how this process works: | |
554 | |
555 @lisp | |
556 (or (if overriding-terminal-local-map | |
557 (@var{find-in} overriding-terminal-local-map) | |
558 (if overriding-local-map | |
559 (@var{find-in} overriding-local-map) | |
560 (or (@var{find-in} (get-text-property (point) 'keymap)) | |
561 (@var{find-in-any} emulation-mode-map-alists) | |
562 (@var{find-in-any} minor-mode-overriding-map-alist) | |
563 (@var{find-in-any} minor-mode-map-alist) | |
564 (if (get-text-property (point) 'local-map)) | |
565 (@var{find-in} (get-text-property (point) 'local-map)) | |
566 (@var{find-in} (current-local-map)))))) | |
567 (@var{find-in} (current-global-map))) | |
568 @end lisp | |
569 | |
570 @noindent | |
571 Here, the pseudo-function @var{find-in} means to look up the key | |
572 sequence in a single map, and @var{find-in-any} means to search the | |
573 appropriate keymaps from an alist. (Searching a single keymap for a | |
574 binding is called @dfn{key lookup}; see @ref{Key Lookup}.) | |
551 | 575 |
552 The @dfn{global keymap} holds the bindings of keys that are defined | 576 The @dfn{global keymap} holds the bindings of keys that are defined |
553 regardless of the current buffer, such as @kbd{C-f}. The variable | 577 regardless of the current buffer, such as @kbd{C-f}. The variable |
554 @code{global-map} holds this keymap, which is always active. | 578 @code{global-map} holds this keymap, which is always active. |
555 | 579 |
595 Emacs has other keymaps that are used in a different way---translating | 619 Emacs has other keymaps that are used in a different way---translating |
596 events within @code{read-key-sequence}. @xref{Translating Input}. | 620 events within @code{read-key-sequence}. @xref{Translating Input}. |
597 | 621 |
598 @xref{Standard Keymaps}, for a list of standard keymaps. | 622 @xref{Standard Keymaps}, for a list of standard keymaps. |
599 | 623 |
624 @defun current-active-maps &optional olp | |
625 This returns the list of active keymaps that would be used by the | |
626 command loop in the current circumstances to look up a key sequence. | |
627 Normally it ignores @code{overriding-local-map} and | |
628 @code{overriding-terminal-local-map}, but if @var{olp} is | |
629 non-@code{nil} then it pays attention to them. | |
630 @end defun | |
631 | |
632 @defun key-binding key &optional accept-defaults no-remap | |
633 This function returns the binding for @var{key} according to the | |
634 current active keymaps. The result is @code{nil} if @var{key} is | |
635 undefined in the keymaps. | |
636 | |
637 @c Emacs 19 feature | |
638 The argument @var{accept-defaults} controls checking for default | |
639 bindings, as in @code{lookup-key} (above). | |
640 | |
641 When commands are remapped (@pxref{Remapping Commands}), | |
642 @code{key-binding} normally processes command remappings so as to | |
643 returns the remapped command that will actually be executed. However, | |
644 if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores | |
645 remappings and returns the binding directly specified for @var{key}. | |
646 | |
647 An error is signaled if @var{key} is not a string or a vector. | |
648 | |
649 @example | |
650 @group | |
651 (key-binding "\C-x\C-f") | |
652 @result{} find-file | |
653 @end group | |
654 @end example | |
655 @end defun | |
656 | |
657 @node Searching Keymaps | |
658 @section Searching the Active Keymaps | |
659 | |
660 After translation of the input events (@pxref{Translating Input}) | |
661 Emacs looks for them in the active keymaps. Here is a pseudo-Lisp | |
662 description of the order in which the active keymaps are searched: | |
663 | |
664 @lisp | |
665 (or (if overriding-terminal-local-map | |
666 (@var{find-in} overriding-terminal-local-map) | |
667 (if overriding-local-map | |
668 (@var{find-in} overriding-local-map) | |
669 (or (@var{find-in} (get-text-property (point) 'keymap)) | |
670 (@var{find-in-any} emulation-mode-map-alists) | |
671 (@var{find-in-any} minor-mode-overriding-map-alist) | |
672 (@var{find-in-any} minor-mode-map-alist) | |
673 (@var{find-in} (get-text-property (point) 'local-map)) | |
674 (@var{find-in} (current-local-map))))) | |
675 (@var{find-in} (current-global-map))) | |
676 @end lisp | |
677 | |
678 @noindent | |
679 The @var{find-in} and @var{find-in-any} are pseudo functions that | |
680 searches in one keymap respectively an alist of keymaps. | |
681 | |
682 @enumerate | |
683 @item | |
684 The function finally found may be remapped | |
685 (@pxref{Remapping Commands}). | |
686 | |
687 @item | |
688 Characters that are bound to @code{self-insert-command} are translated | |
689 according to @code{translation-table-for-input} before insertion. | |
690 | |
691 @item | |
692 @code{current-active-maps} returns a list of the | |
693 currently active keymaps at point. | |
694 | |
695 @item | |
696 When a match is found (@pxref{Key Lookup}), if the binding in the | |
697 keymap is a function, the search is over. However if the keymap entry | |
698 is a symbol with a value or a string, Emacs replaces the input key | |
699 sequences with the variable's value or the string, and restarts the | |
700 search of the active keymaps. | |
701 @end enumerate | |
702 | |
703 @node Controlling Active Maps | |
704 @section Controlling the Active Keymaps | |
705 | |
600 @defvar global-map | 706 @defvar global-map |
601 This variable contains the default global keymap that maps Emacs | 707 This variable contains the default global keymap that maps Emacs |
602 keyboard input to commands. The global keymap is normally this keymap. | 708 keyboard input to commands. The global keymap is normally this |
603 The default global keymap is a full keymap that binds | 709 keymap. The default global keymap is a full keymap that binds |
604 @code{self-insert-command} to all of the printing characters. | 710 @code{self-insert-command} to all of the printing characters. |
605 | 711 |
606 It is normal practice to change the bindings in the global keymap, but you | 712 It is normal practice to change the bindings in the global keymap, but you |
607 should not assign this variable any value other than the keymap it starts | 713 should not assign this variable any value other than the keymap it starts |
608 out with. | 714 out with. |
761 @section Key Lookup | 867 @section Key Lookup |
762 @cindex key lookup | 868 @cindex key lookup |
763 @cindex keymap entry | 869 @cindex keymap entry |
764 | 870 |
765 @dfn{Key lookup} is the process of finding the binding of a key | 871 @dfn{Key lookup} is the process of finding the binding of a key |
766 sequence from a given keymap. Actual execution of the binding is not | 872 sequence from a given keymap. The execution or use of the binding is |
767 part of key lookup. | 873 not part of key lookup. |
768 | 874 |
769 Key lookup uses just the event type of each event in the key sequence; | 875 Key lookup uses just the event type of each event in the key sequence; |
770 the rest of the event is ignored. In fact, a key sequence used for key | 876 the rest of the event is ignored. In fact, a key sequence used for key |
771 lookup may designate a mouse event with just its types (a symbol) | 877 lookup may designate a mouse event with just its types (a symbol) |
772 instead of the entire event (a list). @xref{Input Events}. Such | 878 instead of the entire event (a list). @xref{Input Events}. Such |
773 a ``key-sequence'' is insufficient for @code{command-execute} to run, | 879 a ``key sequence'' is insufficient for @code{command-execute} to run, |
774 but it is sufficient for looking up or rebinding a key. | 880 but it is sufficient for looking up or rebinding a key. |
775 | 881 |
776 When the key sequence consists of multiple events, key lookup | 882 When the key sequence consists of multiple events, key lookup |
777 processes the events sequentially: the binding of the first event is | 883 processes the events sequentially: the binding of the first event is |
778 found, and must be a keymap; then the second event's binding is found in | 884 found, and must be a keymap; then the second event's binding is found in |
963 @deffn Command undefined | 1069 @deffn Command undefined |
964 Used in keymaps to undefine keys. It calls @code{ding}, but does | 1070 Used in keymaps to undefine keys. It calls @code{ding}, but does |
965 not cause an error. | 1071 not cause an error. |
966 @end deffn | 1072 @end deffn |
967 | 1073 |
968 @defun key-binding key &optional accept-defaults no-remap | |
969 This function returns the binding for @var{key} in the current | |
970 keymaps, trying all the active keymaps. The result is @code{nil} if | |
971 @var{key} is undefined in the keymaps. | |
972 | |
973 @c Emacs 19 feature | |
974 The argument @var{accept-defaults} controls checking for default | |
975 bindings, as in @code{lookup-key} (above). | |
976 | |
977 When commands are remapped (@pxref{Remapping Commands}), | |
978 @code{key-binding} normally processes command remappings so as to | |
979 returns the remapped command that will actually be executed. However, | |
980 if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores | |
981 remappings and returns the binding directly specified for @var{key}. | |
982 | |
983 An error is signaled if @var{key} is not a string or a vector. | |
984 | |
985 @example | |
986 @group | |
987 (key-binding "\C-x\C-f") | |
988 @result{} find-file | |
989 @end group | |
990 @end example | |
991 @end defun | |
992 | |
993 @defun current-active-maps &optional olp | |
994 This returns the list of keymaps that would be used by the command | |
995 loop in the current circumstances to look up a key sequence. Normally | |
996 it ignores @code{overriding-local-map} and | |
997 @code{overriding-terminal-local-map}, but if @var{olp} is | |
998 non-@code{nil} then it pays attention to them. | |
999 @end defun | |
1000 | |
1001 @defun local-key-binding key &optional accept-defaults | 1074 @defun local-key-binding key &optional accept-defaults |
1002 This function returns the binding for @var{key} in the current | 1075 This function returns the binding for @var{key} in the current |
1003 local keymap, or @code{nil} if it is undefined there. | 1076 local keymap, or @code{nil} if it is undefined there. |
1004 | 1077 |
1005 @c Emacs 19 feature | 1078 @c Emacs 19 feature |
1034 bindings, as in @code{lookup-key} (above). | 1107 bindings, as in @code{lookup-key} (above). |
1035 @end defun | 1108 @end defun |
1036 | 1109 |
1037 @defvar meta-prefix-char | 1110 @defvar meta-prefix-char |
1038 @cindex @key{ESC} | 1111 @cindex @key{ESC} |
1039 This variable is the meta-prefix character code. It is used when | 1112 This variable is the meta-prefix character code. It is used for |
1040 translating a meta character to a two-character sequence so it can be | 1113 translating a meta character to a two-character sequence so it can be |
1041 looked up in a keymap. For useful results, the value should be a prefix | 1114 looked up in a keymap. For useful results, the value should be a |
1042 event (@pxref{Prefix Keys}). The default value is 27, which is the | 1115 prefix event (@pxref{Prefix Keys}). The default value is 27, which is |
1043 @acronym{ASCII} code for @key{ESC}. | 1116 the @acronym{ASCII} code for @key{ESC}. |
1044 | 1117 |
1045 As long as the value of @code{meta-prefix-char} remains 27, key lookup | 1118 As long as the value of @code{meta-prefix-char} remains 27, key lookup |
1046 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined | 1119 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined |
1047 as the @code{backward-word} command. However, if you were to set | 1120 as the @code{backward-word} command. However, if you were to set |
1048 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will | 1121 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will |