1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004 |
4 |
@c Free Software Foundation, Inc. |
@c Free Software Foundation, Inc. |
5 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
6 |
@setfilename ../info/keymaps |
@setfilename ../info/keymaps |
103 |
This macro converts the text @var{keyseq-text} (a string constant) |
This macro converts the text @var{keyseq-text} (a string constant) |
104 |
into a key sequence (a string or vector constant). The contents |
into a key sequence (a string or vector constant). The contents |
105 |
of @var{keyseq-text} should describe the key sequence using the syntax |
of @var{keyseq-text} should describe the key sequence using the syntax |
106 |
used in this manual: |
used in this manual. More precisely, it uses the same syntax that |
107 |
|
Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard |
108 |
|
Macro,,, emacs, The GNU Emacs Manual}). |
109 |
|
|
110 |
@example |
@example |
111 |
(kbd "C-x") @result{} "\C-x" |
(kbd "C-x") @result{} "\C-x" |
112 |
(kbd "C-x C-f") @result{} "\C-x\C-f" |
(kbd "C-x C-f") @result{} "\C-x\C-f" |
|
(kbd "C-c C-c") @result{} "\C-c\C-c" |
|
113 |
(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" |
(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" |
114 |
(kbd "X") @result{} "X" |
(kbd "X") @result{} "X" |
115 |
(kbd "RET") @result{} "\^M" |
(kbd "RET") @result{} "\^M" |
116 |
(kbd "C-c 3") @result{} "\C-c3" |
(kbd "C-c SPC") @result{} "\C-c@ " |
117 |
|
(kbd "<f1> SPC") @result{} [f1 32] |
118 |
|
(kbd "C-M-<down>") @result{} [C-M-down] |
119 |
@end example |
@end example |
120 |
@end defmac |
@end defmac |
121 |
|
|
147 |
elements of the keymap is given @var{binding} as its binding. Default |
elements of the keymap is given @var{binding} as its binding. Default |
148 |
bindings allow a keymap to bind all possible event types without having |
bindings allow a keymap to bind all possible event types without having |
149 |
to enumerate all of them. A keymap that has a default binding |
to enumerate all of them. A keymap that has a default binding |
150 |
completely masks any lower-precedence keymap. |
completely masks any lower-precedence keymap, except for events |
151 |
|
explicitly bound to @code{nil} (see below). |
152 |
|
|
153 |
@item @var{char-table} |
@item @var{char-table} |
154 |
If an element of a keymap is a char-table, it counts as holding |
If an element of a keymap is a char-table, it counts as holding |
255 |
@c ??? This should come after make-sparse-keymap |
@c ??? This should come after make-sparse-keymap |
256 |
@defun make-keymap &optional prompt |
@defun make-keymap &optional prompt |
257 |
This function creates and returns a new full keymap. That keymap |
This function creates and returns a new full keymap. That keymap |
258 |
contains a char-table (@pxref{Char-Tables}) with 384 slots: the first |
contains a char-table (@pxref{Char-Tables}) with slots for all |
259 |
128 slots are for defining all the @acronym{ASCII} characters, the next 128 |
characters without modifiers. The new keymap initially binds all |
260 |
slots are for 8-bit European characters, and each one of the final 128 |
these characters to @code{nil}, and does not bind any other kind of |
261 |
slots is for one character set of non-@acronym{ASCII} characters supported by |
event. |
|
Emacs. The new keymap initially binds all these characters to |
|
|
@code{nil}, and does not bind any other kind of event. |
|
262 |
|
|
263 |
@example |
@example |
264 |
@group |
@group |
265 |
(make-keymap) |
(make-keymap) |
266 |
@result{} (keymap [nil nil nil @dots{} nil nil]) |
@result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) |
267 |
@end group |
@end group |
268 |
@end example |
@end example |
269 |
|
|
511 |
|
|
512 |
@defun define-prefix-command symbol &optional mapvar prompt |
@defun define-prefix-command symbol &optional mapvar prompt |
513 |
@cindex prefix command |
@cindex prefix command |
514 |
|
@anchor{Definition of define-prefix-command} |
515 |
This function prepares @var{symbol} for use as a prefix key's binding: |
This function prepares @var{symbol} for use as a prefix key's binding: |
516 |
it creates a sparse keymap and stores it as @var{symbol}'s function |
it creates a sparse keymap and stores it as @var{symbol}'s function |
517 |
definition. Subsequently binding a key sequence to @var{symbol} will |
definition. Subsequently binding a key sequence to @var{symbol} will |
701 |
|
|
702 |
@defvar overriding-local-map |
@defvar overriding-local-map |
703 |
If non-@code{nil}, this variable holds a keymap to use instead of the |
If non-@code{nil}, this variable holds a keymap to use instead of the |
704 |
buffer's local keymap and instead of all the minor mode keymaps. This |
buffer's local keymap, text property or overlay keymaps, and instead |
705 |
keymap, if any, overrides all other maps that would have been active, |
of all the minor mode keymaps. This keymap, if any, overrides all |
706 |
except for the current global map. |
other maps that would have been active, except for the current global |
707 |
|
map. |
708 |
@end defvar |
@end defvar |
709 |
|
|
710 |
@defvar overriding-terminal-local-map |
@defvar overriding-terminal-local-map |
711 |
If non-@code{nil}, this variable holds a keymap to use instead of |
If non-@code{nil}, this variable holds a keymap to use instead of |
712 |
@code{overriding-local-map}, the buffer's local keymap and all the minor |
@code{overriding-local-map}, the buffer's local keymap, text property |
713 |
mode keymaps. |
or overlay keymaps, and all the minor mode keymaps. |
714 |
|
|
715 |
This variable is always local to the current terminal and cannot be |
This variable is always local to the current terminal and cannot be |
716 |
buffer-local. @xref{Multiple Displays}. It is used to implement |
buffer-local. @xref{Multiple Displays}. It is used to implement |
981 |
@end example |
@end example |
982 |
@end defun |
@end defun |
983 |
|
|
984 |
@defun current-active-maps |
@defun current-active-maps &optional olp |
985 |
This returns the list of keymaps that would be used by the command |
This returns the list of keymaps that would be used by the command |
986 |
loop in the current circumstances to look up a key sequence. |
loop in the current circumstances to look up a key sequence. Normally |
987 |
|
it ignores @code{overriding-local-map} and |
988 |
|
@code{overriding-terminal-local-map}, but if @var{olp} is |
989 |
|
non-@code{nil} then it pays attention to them. |
990 |
@end defun |
@end defun |
991 |
|
|
992 |
@defun local-key-binding key &optional accept-defaults |
@defun local-key-binding key &optional accept-defaults |
1198 |
default global map. |
default global map. |
1199 |
|
|
1200 |
The function @code{substitute-key-definition} scans a keymap for |
The function @code{substitute-key-definition} scans a keymap for |
1201 |
keys that have a certain binding and rebind them with a different |
keys that have a certain binding and rebinds them with a different |
1202 |
binding. Another feature you can use for similar effects, but which |
binding. Another feature you can use for similar effects, but which |
1203 |
is often cleaner, is to add a binding that remaps a command |
is often cleaner, is to add a binding that remaps a command |
1204 |
(@pxref{Remapping Commands}). |
(@pxref{Remapping Commands}). |
1331 |
Whenever @code{my-mode-map} is an active keymap, if the user types |
Whenever @code{my-mode-map} is an active keymap, if the user types |
1332 |
@kbd{C-k}, Emacs will find the standard global binding of |
@kbd{C-k}, Emacs will find the standard global binding of |
1333 |
@code{kill-line} (assuming nobody has changed it). But |
@code{kill-line} (assuming nobody has changed it). But |
1334 |
@code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map}, |
@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line}, |
1335 |
so instead of running @code{kill-line}, Emacs runs |
so instead of running @code{kill-line}, Emacs runs |
1336 |
@code{my-kill-line}. |
@code{my-kill-line}. |
1337 |
|
|
1344 |
|
|
1345 |
@noindent |
@noindent |
1346 |
does not have the effect of remapping @code{kill-line} into |
does not have the effect of remapping @code{kill-line} into |
1347 |
@code{my-other-kill-line}. If an ordinary key binding specifies |
@code{my-other-kill-line}. If an ordinary key binding specifies |
1348 |
@code{kill-line}, this keymap will remap it to @code{my-kill-line}; |
@code{kill-line}, this keymap will remap it to @code{my-kill-line}; |
1349 |
if an ordinary binding specifies @code{my-kill-line}, this keymap will |
if an ordinary binding specifies @code{my-kill-line}, this keymap will |
1350 |
remap it to @code{my-other-kill-line}. |
remap it to @code{my-other-kill-line}. |
1351 |
|
|
1352 |
@defun command-remapping command |
@defun command-remapping command |
1353 |
This function returns the remapping for @var{command}, given the |
This function returns the remapping for @var{command} (a symbol), |
1354 |
current active keymaps. If @var{command} is not remapped (which is |
given the current active keymaps. If @var{command} is not remapped |
1355 |
the usual situation), the function returns @code{nil}. |
(which is the usual situation), or not a symbol, the function returns |
1356 |
|
@code{nil}. |
1357 |
@end defun |
@end defun |
1358 |
|
|
1359 |
@node Key Binding Commands |
@node Key Binding Commands |
1417 |
Latin-1 character with code 246 (@kbd{M-v}). In order to use this |
Latin-1 character with code 246 (@kbd{M-v}). In order to use this |
1418 |
binding, you need to enter the multibyte Latin-1 character as keyboard |
binding, you need to enter the multibyte Latin-1 character as keyboard |
1419 |
input. One way to do this is by using an appropriate input method |
input. One way to do this is by using an appropriate input method |
1420 |
(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}). |
(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). |
1421 |
|
|
1422 |
If you want to use a unibyte character in the key binding, you can |
If you want to use a unibyte character in the key binding, you can |
1423 |
construct the key sequence string using @code{multibyte-char-to-unibyte} |
construct the key sequence string using @code{multibyte-char-to-unibyte} |
1507 |
@var{keymap} is @var{map}. |
@var{keymap} is @var{map}. |
1508 |
|
|
1509 |
The elements of the alist are ordered so that the @var{key} increases |
The elements of the alist are ordered so that the @var{key} increases |
1510 |
in length. The first element is always @code{("" .@: @var{keymap})}, |
in length. The first element is always @code{([] .@: @var{keymap})}, |
1511 |
because the specified keymap is accessible from itself with a prefix of |
because the specified keymap is accessible from itself with a prefix of |
1512 |
no events. |
no events. |
1513 |
|
|
1525 |
@smallexample |
@smallexample |
1526 |
@group |
@group |
1527 |
(accessible-keymaps (current-local-map)) |
(accessible-keymaps (current-local-map)) |
1528 |
@result{}(("" keymap |
@result{}(([] keymap |
1529 |
(27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} |
(27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} |
1530 |
(83 . center-paragraph) |
(83 . center-paragraph) |
1531 |
(115 . center-line)) |
(115 . center-line)) |
1549 |
@smallexample |
@smallexample |
1550 |
@group |
@group |
1551 |
(accessible-keymaps (current-global-map)) |
(accessible-keymaps (current-global-map)) |
1552 |
@result{} (("" keymap [set-mark-command beginning-of-line @dots{} |
@result{} (([] keymap [set-mark-command beginning-of-line @dots{} |
1553 |
delete-backward-char]) |
delete-backward-char]) |
1554 |
@end group |
@end group |
1555 |
@group |
@group |
1580 |
for each binding in @var{keymap}. It passes two arguments, |
for each binding in @var{keymap}. It passes two arguments, |
1581 |
the event type and the value of the binding. If @var{keymap} |
the event type and the value of the binding. If @var{keymap} |
1582 |
has a parent, the parent's bindings are included as well. |
has a parent, the parent's bindings are included as well. |
1583 |
|
This works recursively: if the parent has itself a parent, then the |
1584 |
|
grandparent's bindings are also included and so on. |
1585 |
|
|
1586 |
This function is the cleanest way to examine all the bindings |
This function is the cleanest way to examine all the bindings |
1587 |
in a keymap. |
in a keymap. |
1590 |
@defun where-is-internal command &optional keymap firstonly noindirect no-remap |
@defun where-is-internal command &optional keymap firstonly noindirect no-remap |
1591 |
This function is a subroutine used by the @code{where-is} command |
This function is a subroutine used by the @code{where-is} command |
1592 |
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list |
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list |
1593 |
of key sequences (of any length) that are bound to @var{command} in a |
of all key sequences (of any length) that are bound to @var{command} in a |
1594 |
set of keymaps. |
set of keymaps. |
1595 |
|
|
1596 |
The argument @var{command} can be any object; it is compared with all |
The argument @var{command} can be any object; it is compared with all |
1598 |
|
|
1599 |
If @var{keymap} is @code{nil}, then the maps used are the current active |
If @var{keymap} is @code{nil}, then the maps used are the current active |
1600 |
keymaps, disregarding @code{overriding-local-map} (that is, pretending |
keymaps, disregarding @code{overriding-local-map} (that is, pretending |
1601 |
its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the |
its value is @code{nil}). If @var{keymap} is a keymap, then the |
1602 |
maps searched are @var{keymap} and the global keymap. If @var{keymap} |
maps searched are @var{keymap} and the global keymap. If @var{keymap} |
1603 |
is a list of keymaps, only those keymaps are searched. |
is a list of keymaps, only those keymaps are searched. |
1604 |
|
|
1608 |
@code{(keymap)} (an empty keymap) as @var{keymap}. |
@code{(keymap)} (an empty keymap) as @var{keymap}. |
1609 |
|
|
1610 |
If @var{firstonly} is @code{non-ascii}, then the value is a single |
If @var{firstonly} is @code{non-ascii}, then the value is a single |
1611 |
string representing the first key sequence found, rather than a list of |
vector representing the first key sequence found, rather than a list of |
1612 |
all possible key sequences. If @var{firstonly} is @code{t}, then the |
all possible key sequences. If @var{firstonly} is @code{t}, then the |
1613 |
value is the first key sequence, except that key sequences consisting |
value is the first key sequence, except that key sequences consisting |
1614 |
entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} |
entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} |
1615 |
characters) are preferred to all other key sequences. |
characters) are preferred to all other key sequences and that the |
1616 |
|
return value can never be a menu binding. |
1617 |
|
|
1618 |
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't |
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't |
1619 |
follow indirect keymap bindings. This makes it possible to search for |
follow indirect keymap bindings. This makes it possible to search for |
1634 |
@end smallexample |
@end smallexample |
1635 |
@end defun |
@end defun |
1636 |
|
|
1637 |
@deffn Command describe-bindings &optional prefix |
@deffn Command describe-bindings &optional prefix buffer-or-name |
1638 |
This function creates a listing of all current key bindings, and |
This function creates a listing of all current key bindings, and |
1639 |
displays it in a buffer named @samp{*Help*}. The text is grouped by |
displays it in a buffer named @samp{*Help*}. The text is grouped by |
1640 |
modes---minor modes first, then the major mode, then global bindings. |
modes---minor modes first, then the major mode, then global bindings. |
1654 |
@kbd{~} is @acronym{ASCII} 126, and the characters between them include all |
@kbd{~} is @acronym{ASCII} 126, and the characters between them include all |
1655 |
the normal printing characters, (e.g., letters, digits, punctuation, |
the normal printing characters, (e.g., letters, digits, punctuation, |
1656 |
etc.@:); all these characters are bound to @code{self-insert-command}. |
etc.@:); all these characters are bound to @code{self-insert-command}. |
1657 |
|
|
1658 |
|
If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a |
1659 |
|
buffer name. Then @code{describe-bindings} lists that buffer's bindings, |
1660 |
|
instead of the current buffer's. |
1661 |
@end deffn |
@end deffn |
1662 |
|
|
1663 |
@node Menu Keymaps |
@node Menu Keymaps |
1696 |
|
|
1697 |
The easiest way to construct a keymap with a prompt string is to specify |
The easiest way to construct a keymap with a prompt string is to specify |
1698 |
the string as an argument when you call @code{make-keymap}, |
the string as an argument when you call @code{make-keymap}, |
1699 |
@code{make-sparse-keymap} or @code{define-prefix-command} |
@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or |
1700 |
(@pxref{Creating Keymaps}). |
@code{define-prefix-command} (@pxref{Definition of define-prefix-command}). |
1701 |
|
|
1702 |
|
|
1703 |
@defun keymap-prompt keymap |
@defun keymap-prompt keymap |
1704 |
This function returns the overall prompt string of @var{keymap}, |
This function returns the overall prompt string of @var{keymap}, |
2123 |
when the user selects from the menu, and they appear in the output of |
when the user selects from the menu, and they appear in the output of |
2124 |
@code{where-is} and @code{apropos}. |
@code{where-is} and @code{apropos}. |
2125 |
|
|
2126 |
|
The menu in this example is intended for use with the mouse. If a |
2127 |
|
menu is intended for use with the keyboard, that is, if it is bound to |
2128 |
|
a key sequence ending with a keyboard event, then the menu items |
2129 |
|
should be bound to characters or ``real'' function keys, that can be |
2130 |
|
typed with the keyboard. |
2131 |
|
|
2132 |
The binding whose definition is @code{("--")} is a separator line. |
The binding whose definition is @code{("--")} is a separator line. |
2133 |
Like a real menu item, the separator has a key symbol, in this case |
Like a real menu item, the separator has a key symbol, in this case |
2134 |
@code{separator-ps-print}. If one menu has two separators, they must |
@code{separator-ps-print}. If one menu has two separators, they must |
2411 |
This function is used for making non-global tool bar items. Use it |
This function is used for making non-global tool bar items. Use it |
2412 |
like @code{tool-bar-add-item-from-menu} except that @var{in-map} |
like @code{tool-bar-add-item-from-menu} except that @var{in-map} |
2413 |
specifies the local map to make the definition in. The argument |
specifies the local map to make the definition in. The argument |
2414 |
@var{from-map} si like the @var{map} argument of |
@var{from-map} is like the @var{map} argument of |
2415 |
@code{tool-bar-add-item-from-menu}. |
@code{tool-bar-add-item-from-menu}. |
2416 |
@end defun |
@end defun |
2417 |
|
|