28 |
* Key Lookup:: How extracting elements from keymaps works. |
* Key Lookup:: How extracting elements from keymaps works. |
29 |
* Functions for Key Lookup:: How to request key lookup. |
* Functions for Key Lookup:: How to request key lookup. |
30 |
* Changing Key Bindings:: Redefining a key in a keymap. |
* Changing Key Bindings:: Redefining a key in a keymap. |
31 |
|
* Remapping Commands:: Bindings that translate one command to another. |
32 |
* Key Binding Commands:: Interactive interfaces for redefining keys. |
* Key Binding Commands:: Interactive interfaces for redefining keys. |
33 |
* Scanning Keymaps:: Looking through all keymaps, for printing help. |
* Scanning Keymaps:: Looking through all keymaps, for printing help. |
34 |
* Menu Keymaps:: Defining a menu as a keymap. |
* Menu Keymaps:: Defining a menu as a keymap. |
125 |
to enumerate all of them. A keymap that has a default binding |
to enumerate all of them. A keymap that has a default binding |
126 |
completely masks any lower-precedence keymap. |
completely masks any lower-precedence keymap. |
127 |
|
|
128 |
@item @var{vector} |
@item @var{char-table} |
129 |
If an element of a keymap is a vector, the vector counts as bindings for |
If an element of a keymap is a char-table, it counts as holding |
130 |
all the @sc{ascii} characters, codes 0 through 127; vector element |
bindings for all character events with no modifier bits |
131 |
@var{n} is the binding for the character with code @var{n}. This is a |
(@pxref{modifier bits}): element @var{n} is the binding for the |
132 |
compact way to record lots of bindings. A keymap with such a vector is |
character with code @var{n}. This is a compact way to record lots of |
133 |
called a @dfn{full keymap}. Other keymaps are called @dfn{sparse |
bindings. A keymap with such a char-table is called a @dfn{full |
134 |
keymaps}. |
keymap}. Other keymaps are called @dfn{sparse keymaps}. |
135 |
|
|
136 |
A @code{nil} binding is used to mean that a key is explicitly not bound. |
When a keymap contains a char-table vector, it always defines a |
137 |
Just like any other binding, it takes precedence over a default binding |
binding for each character without modifiers. However, if the binding |
138 |
or a binding in the parent keymap, but on the other hand, it does not |
is @code{nil}, it doesn't constitute a definition. @code{nil} takes |
139 |
take precedence over keymaps of lower priority. |
precedence over a default binding or a binding in the parent keymap. |
140 |
|
So in a full keymap, default bindings are not meaningful for |
141 |
When a keymap contains a vector, it always defines a binding for each |
characters without modifiers. They can still apply to characters with |
142 |
@sc{ascii} character, even if the vector contains @code{nil} for that |
modifier bits and to non-character events. A binding of @code{nil} |
143 |
character. Such a binding of @code{nil} overrides any default key |
does @emph{not} override lower-precedence keymaps; thus, if the local |
144 |
binding in the keymap, for @sc{ascii} characters. However, default |
map gives a binding of @code{nil}, Emacs uses the binding from the |
145 |
bindings are still meaningful for events other than @sc{ascii} |
global map. |
|
characters. A binding of @code{nil} does @emph{not} override |
|
|
lower-precedence keymaps; thus, if the local map gives a binding of |
|
|
@code{nil}, Emacs uses the binding from the global map. |
|
146 |
|
|
147 |
@item @var{string} |
@item @var{string} |
148 |
@cindex keymap prompt string |
@cindex keymap prompt string |
528 |
|
|
529 |
The variable @code{overriding-local-map}, if non-@code{nil}, specifies |
The variable @code{overriding-local-map}, if non-@code{nil}, specifies |
530 |
another local keymap that overrides the buffer's local map and all the |
another local keymap that overrides the buffer's local map and all the |
531 |
minor mode keymaps. |
minor mode keymaps. Modes for emulation can specify additional |
532 |
|
active keymaps through the variable @code{emulation-mode-map-alists}. |
533 |
|
|
534 |
All the active keymaps are used together to determine what command to |
All the active keymaps are used together to determine what command to |
535 |
execute when a key is entered. Emacs searches these maps one by one, in |
execute when a key is entered. Emacs searches these maps one by one, in |
713 |
event is run directly by @code{read-event}. @xref{Special Events}. |
event is run directly by @code{read-event}. @xref{Special Events}. |
714 |
@end defvar |
@end defvar |
715 |
|
|
716 |
|
@defvar emulation-mode-map-alists |
717 |
|
This variable holds a list of keymap alists to use for emulations |
718 |
|
modes. It is intended for modes or packages using multiple minor-mode |
719 |
|
keymaps. Each element is a keymap alist which has the same format and |
720 |
|
meaning as @code{minor-mode-map-alist}, or a symbol with a variable |
721 |
|
binding which is such an alist. The ``active'' keymaps in each alist |
722 |
|
are used before @code{minor-mode-map-alist} and |
723 |
|
@code{minor-mode-overriding-map-alist}. |
724 |
|
@end defvar |
725 |
|
|
726 |
@node Key Lookup |
@node Key Lookup |
727 |
@section Key Lookup |
@section Key Lookup |
728 |
@cindex key lookup |
@cindex key lookup |
927 |
not cause an error. |
not cause an error. |
928 |
@end deffn |
@end deffn |
929 |
|
|
930 |
@defun key-binding key &optional accept-defaults |
@defun key-binding key &optional accept-defaults no-remap |
931 |
This function returns the binding for @var{key} in the current |
This function returns the binding for @var{key} in the current |
932 |
keymaps, trying all the active keymaps. The result is @code{nil} if |
keymaps, trying all the active keymaps. The result is @code{nil} if |
933 |
@var{key} is undefined in the keymaps. |
@var{key} is undefined in the keymaps. |
936 |
The argument @var{accept-defaults} controls checking for default |
The argument @var{accept-defaults} controls checking for default |
937 |
bindings, as in @code{lookup-key} (above). |
bindings, as in @code{lookup-key} (above). |
938 |
|
|
939 |
|
When commands are remapped (@pxref{Remapping Commands}), |
940 |
|
@code{key-binding} normally processes command remappings so as to |
941 |
|
returns the remapped command that will actually be executed. However, |
942 |
|
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores |
943 |
|
remappings and returns the binding directly specified for @var{key}. |
944 |
|
|
945 |
An error is signaled if @var{key} is not a string or a vector. |
An error is signaled if @var{key} is not a string or a vector. |
946 |
|
|
947 |
@example |
@example |
952 |
@end example |
@end example |
953 |
@end defun |
@end defun |
954 |
|
|
955 |
|
@defun current-active-maps |
956 |
|
This returns the list of keymaps that would be used by the command |
957 |
|
loop in the current circumstances to look up a key sequence. |
958 |
|
@end defun |
959 |
|
|
960 |
@defun local-key-binding key &optional accept-defaults |
@defun local-key-binding key &optional accept-defaults |
961 |
This function returns the binding for @var{key} in the current |
This function returns the binding for @var{key} in the current |
962 |
local keymap, or @code{nil} if it is undefined there. |
local keymap, or @code{nil} if it is undefined there. |
1165 |
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the |
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the |
1166 |
default global map. |
default global map. |
1167 |
|
|
1168 |
|
The function @code{substitute-key-definition} scans a keymap for |
1169 |
|
keys that have a certain binding and rebind them with a different |
1170 |
|
binding. Another feature you can use for similar effects, but which |
1171 |
|
is often cleaner, is to add a binding that remaps a command |
1172 |
|
(@pxref{Remapping Commands}). |
1173 |
|
|
1174 |
@defun substitute-key-definition olddef newdef keymap &optional oldmap |
@defun substitute-key-definition olddef newdef keymap &optional oldmap |
1175 |
@cindex replace bindings |
@cindex replace bindings |
1176 |
This function replaces @var{olddef} with @var{newdef} for any keys in |
This function replaces @var{olddef} with @var{newdef} for any keys in |
1205 |
puts the special deletion command in @code{my-map} for whichever keys |
puts the special deletion command in @code{my-map} for whichever keys |
1206 |
are globally bound to the standard deletion command. |
are globally bound to the standard deletion command. |
1207 |
|
|
|
@ignore |
|
|
@c Emacs 18 only |
|
|
Prefix keymaps that appear within @var{keymap} are not checked |
|
|
recursively for keys bound to @var{olddef}; they are not changed at all. |
|
|
Perhaps it would be better to check nested keymaps recursively. |
|
|
@end ignore |
|
|
|
|
1208 |
Here is an example showing a keymap before and after substitution: |
Here is an example showing a keymap before and after substitution: |
1209 |
|
|
1210 |
@smallexample |
@smallexample |
1273 |
@end smallexample |
@end smallexample |
1274 |
@end defun |
@end defun |
1275 |
|
|
1276 |
|
@node Remapping Commands |
1277 |
|
@section Remapping Commands |
1278 |
|
@cindex remapping commands |
1279 |
|
|
1280 |
|
A special kind of key binding, using a special ``key sequence'' |
1281 |
|
which includes a command name, has the effect of @dfn{remapping} that |
1282 |
|
command into another. Here's how it works. You make a key binding |
1283 |
|
for a key sequence that starts with the dummy event @code{remap}, |
1284 |
|
followed by the command name you want to remap. Specify the remapped |
1285 |
|
definition as the definition in this binding. The remapped definition |
1286 |
|
is usually a command name, but it can be any valid definition for |
1287 |
|
a key binding. |
1288 |
|
|
1289 |
|
Here's an example. Suppose that My mode uses special commands |
1290 |
|
@code{my-kill-line} and @code{my-kill-word}, which should be invoked |
1291 |
|
instead of @code{kill-line} and @code{kill-word}. It can establish |
1292 |
|
this by making these two command-remapping bindings in its keymap: |
1293 |
|
|
1294 |
|
@example |
1295 |
|
(define-key my-mode-map [remap kill-line] 'my-kill-line) |
1296 |
|
(define-key my-mode-map [remap kill-word] 'my-kill-word) |
1297 |
|
@end example |
1298 |
|
|
1299 |
|
Whenever @code{my-mode-map} is an active keymap, if the user types |
1300 |
|
@kbd{C-k}, Emacs will find the standard global binding of |
1301 |
|
@code{kill-line} (assuming nobody has changed it). But |
1302 |
|
@code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map}, |
1303 |
|
so instead of running @code{kill-line}, Emacs runs |
1304 |
|
@code{my-kill-line}. |
1305 |
|
|
1306 |
|
Remapping only works through a single level. In other words, |
1307 |
|
|
1308 |
|
@example |
1309 |
|
(define-key my-mode-map [remap kill-line] 'my-kill-line) |
1310 |
|
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) |
1311 |
|
@end example |
1312 |
|
|
1313 |
|
@noindent |
1314 |
|
does not have the effect of remapping @code{kill-line} into |
1315 |
|
@code{my-other-kill-line}. If an ordinary key binding specifies |
1316 |
|
@code{kill-line}, this keymap will remap it to @code{my-kill-line}; |
1317 |
|
if an ordinary binding specifies @code{my-kill-line}, this keymap will |
1318 |
|
remap it to @code{my-other-kill-line}. |
1319 |
|
|
1320 |
|
@defun command-remapping command |
1321 |
|
This function returns the remapping for @var{command}, given the |
1322 |
|
current active keymaps. If @var{command} is not remapped (which is |
1323 |
|
the usual situation), the function returns @code{nil}. |
1324 |
|
@end defun |
1325 |
|
|
1326 |
@node Key Binding Commands |
@node Key Binding Commands |
1327 |
@section Commands for Binding Keys |
@section Commands for Binding Keys |
1328 |
|
|
1542 |
These are not all the keymaps you would see in actuality. |
These are not all the keymaps you would see in actuality. |
1543 |
@end defun |
@end defun |
1544 |
|
|
1545 |
@defun where-is-internal command &optional keymap firstonly noindirect |
@defun map-keymap function keymap |
1546 |
|
The function @code{map-keymap} calls @var{function} once |
1547 |
|
for each binding in @var{keymap}. It passes two arguments, |
1548 |
|
the event type and the value of the binding. If @var{keymap} |
1549 |
|
has a parent, the parent's bindings are included as well. |
1550 |
|
|
1551 |
|
This function is the cleanest way to examine all the bindings |
1552 |
|
in a keymap. |
1553 |
|
@end defun |
1554 |
|
|
1555 |
|
@defun where-is-internal command &optional keymap firstonly noindirect no-remap |
1556 |
This function is a subroutine used by the @code{where-is} command |
This function is a subroutine used by the @code{where-is} command |
1557 |
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list |
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list |
1558 |
of key sequences (of any length) that are bound to @var{command} in a |
of key sequences (of any length) that are bound to @var{command} in a |
1583 |
follow indirect keymap bindings. This makes it possible to search for |
follow indirect keymap bindings. This makes it possible to search for |
1584 |
an indirect definition itself. |
an indirect definition itself. |
1585 |
|
|
1586 |
|
When command remapping is in effect (@pxref{Remapping Commands}), |
1587 |
|
@code{where-is-internal} figures out when a command will be run due to |
1588 |
|
remapping and reports keys accordingly. It also returns @code{nil} if |
1589 |
|
@var{command} won't really be run because it has been remapped to some |
1590 |
|
other command. However, if @var{no-remap} is non-@code{nil}. |
1591 |
|
@code{where-is-internal} ignores remappings. |
1592 |
|
|
1593 |
@smallexample |
@smallexample |
1594 |
@group |
@group |
1595 |
(where-is-internal 'describe-function) |
(where-is-internal 'describe-function) |
1659 |
@code{make-sparse-keymap} or @code{define-prefix-command} |
@code{make-sparse-keymap} or @code{define-prefix-command} |
1660 |
(@pxref{Creating Keymaps}). |
(@pxref{Creating Keymaps}). |
1661 |
|
|
1662 |
|
@defun keymap-prompt keymap |
1663 |
|
This function returns the overall prompt string of @var{keymap}, |
1664 |
|
or @code{nil} if it has none. |
1665 |
|
@end defun |
1666 |
|
|
1667 |
The order of items in the menu is the same as the order of bindings in |
The order of items in the menu is the same as the order of bindings in |
1668 |
the keymap. Since @code{define-key} puts new bindings at the front, you |
the keymap. Since @code{define-key} puts new bindings at the front, you |
1669 |
should define the menu items starting at the bottom of the menu and |
should define the menu items starting at the bottom of the menu and |
1694 |
@noindent |
@noindent |
1695 |
The @sc{car}, @var{item-string}, is the string to be displayed in the |
The @sc{car}, @var{item-string}, is the string to be displayed in the |
1696 |
menu. It should be short---preferably one to three words. It should |
menu. It should be short---preferably one to three words. It should |
1697 |
describe the action of the command it corresponds to. |
describe the action of the command it corresponds to. Note that it is |
1698 |
|
not generally possible to display non-ASCII text in menus. It will |
1699 |
|
work for keyboard menus and will work to a large extent when Emacs is |
1700 |
|
built with Gtk+ support.@footnote{In this case, the text is first |
1701 |
|
encoded using the @code{utf-8} coding system and then rendered by the |
1702 |
|
toolkit as it sees fit.} |
1703 |
|
|
1704 |
You can also supply a second string, called the help string, as follows: |
You can also supply a second string, called the help string, as follows: |
1705 |
|
|
2346 |
|
|
2347 |
@defun tool-bar-add-item-from-menu command icon &optional map &rest props |
@defun tool-bar-add-item-from-menu command icon &optional map &rest props |
2348 |
@tindex tool-bar-add-item-from-menu |
@tindex tool-bar-add-item-from-menu |
2349 |
This command is a convenience for defining tool bar items which are |
This function is a convenience for defining tool bar items which are |
2350 |
consistent with existing menu bar bindings. The binding of |
consistent with existing menu bar bindings. The binding of |
2351 |
@var{command} is looked up in the menu bar in @var{map} (default |
@var{command} is looked up in the menu bar in @var{map} (default |
2352 |
@code{global-map}) and modified to add an image specification for |
@code{global-map}) and modified to add an image specification for |
2353 |
@var{icon}, which is looked for in the same way as by |
@var{icon}, which is found in the same way as by |
2354 |
@code{tool-bar-add-item}. The resulting binding is then placed in |
@code{tool-bar-add-item}. The resulting binding is then placed in |
2355 |
@code{tool-bar-map}. @var{map} must contain an appropriate keymap bound |
@code{tool-bar-map}, so use this function only for global tool bar |
2356 |
to @code{[menu-bar]}. The remaining arguments @var{props} are |
items. |
2357 |
additional property list elements to add to the menu item specification. |
|
2358 |
|
@var{map} must contain an appropriate keymap bound to |
2359 |
|
@code{[menu-bar]}. The remaining arguments @var{props} are additional |
2360 |
|
property list elements to add to the menu item specification. |
2361 |
|
@end defun |
2362 |
|
|
2363 |
|
@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props |
2364 |
|
This function is used for making non-global tool bar items. Use it |
2365 |
|
like @code{tool-bar-add-item-from-menu} except that @var{in-map} |
2366 |
|
specifies the local map to make the definition in. The argument |
2367 |
|
@var{from-map} si like the @var{map} argument of |
2368 |
|
@code{tool-bar-add-item-from-menu}. |
2369 |
@end defun |
@end defun |
2370 |
|
|
2371 |
@tindex auto-resize-tool-bar |
@tindex auto-resize-tool-bar |
2458 |
[work] '("Work" . work-command) 'break) |
[work] '("Work" . work-command) 'break) |
2459 |
@end example |
@end example |
2460 |
@end defun |
@end defun |
2461 |
|
|
2462 |
|
@ignore |
2463 |
|
arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 |
2464 |
|
@end ignore |