Start adjusting the manuals to talk about the keymap-* functions
* lisp/dired.el (dired--make-directory-clickable): * doc/lispref/keymaps.texi (Keymaps): (Key Sequences): (Prefix Keys): (Active Keymaps): (Key Lookup): (Functions for Key Lookup): (Changing Key Bindings): (Key Binding Commands): (Tool Bar): * doc/lispref/commands.texi (Interactive Codes): (Event Examples): (Event Mod): * doc/emacs/kmacro.texi (Save Keyboard Macro): * doc/emacs/custom.texi (Keymaps): (Keymaps): (Minibuffer Maps): (Rebinding): (Init Rebinding): (Modifier Keys): (Mouse Buttons): (Init Examples): (Init Non-ASCII): Adjust the documentation to remove description of the old syntaxes, and use the new keymap-* functions. * doc/lispref/keymaps.texi (Low-Level Key Binding): New node that describes `define-key' and the old key syntaxes.
This commit is contained in:
Lars Ingebrigtsen
parent
2daffe3550
commit
331366395e
6 changed files with 225 additions and 272 deletions
|
|
@ -1584,7 +1584,7 @@ which overrides the global definitions of some keys.
|
|||
self-inserting because the global keymap binds it to the command
|
||||
@code{self-insert-command}. The standard Emacs editing characters
|
||||
such as @kbd{C-a} also get their standard meanings from the global
|
||||
keymap. Commands to rebind keys, such as @kbd{M-x global-set-key},
|
||||
keymap. Commands to rebind keys, such as @kbd{M-x keymap-global-set},
|
||||
work by storing the new binding in the proper place in the global map
|
||||
(@pxref{Rebinding}). To view the current key bindings, use the
|
||||
@kbd{C-h b} command.
|
||||
|
|
@ -1736,8 +1736,8 @@ them, it may be convenient to disable completion on those keys by
|
|||
putting this in your init file:
|
||||
|
||||
@lisp
|
||||
(define-key minibuffer-local-completion-map " " 'self-insert-command)
|
||||
(define-key minibuffer-local-completion-map "?" 'self-insert-command)
|
||||
(keymap-set minibuffer-local-completion-map "SPC" 'self-insert-command)
|
||||
(keymap-set minibuffer-local-completion-map "?" 'self-insert-command)
|
||||
@end lisp
|
||||
|
||||
@node Rebinding
|
||||
|
|
@ -1756,19 +1756,19 @@ local keymap, which affects all buffers using the same major mode.
|
|||
Emacs session. @xref{Init Rebinding}, for a description of how to
|
||||
make key rebindings affect future Emacs sessions.
|
||||
|
||||
@findex global-set-key
|
||||
@findex local-set-key
|
||||
@findex global-unset-key
|
||||
@findex local-unset-key
|
||||
@findex keymap-global-set
|
||||
@findex keymap-local-set
|
||||
@findex keymap-global-unset
|
||||
@findex keymap-local-unset
|
||||
@table @kbd
|
||||
@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
|
||||
@item M-x keymap-global-set @key{RET} @var{key} @var{cmd} @key{RET}
|
||||
Define @var{key} globally to run @var{cmd}.
|
||||
@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
|
||||
@item M-x keymap-local-set @key{RET} @var{key} @var{cmd} @key{RET}
|
||||
Define @var{key} locally (in the major mode now in effect) to run
|
||||
@var{cmd}.
|
||||
@item M-x global-unset-key @key{RET} @var{key}
|
||||
@item M-x keymap-global-unset @key{RET} @var{key}
|
||||
Make @var{key} undefined in the global map.
|
||||
@item M-x local-unset-key @key{RET} @var{key}
|
||||
@item M-x keymap-local-unset @key{RET} @var{key}
|
||||
Make @var{key} undefined locally (in the major mode now in effect).
|
||||
@end table
|
||||
|
||||
|
|
@ -1777,11 +1777,11 @@ command (@pxref{Interactive Shell}), replacing the normal global
|
|||
definition of @kbd{C-z}:
|
||||
|
||||
@example
|
||||
M-x global-set-key @key{RET} C-z shell @key{RET}
|
||||
M-x keymap-global-set @key{RET} C-z shell @key{RET}
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The @code{global-set-key} command reads the command name after the
|
||||
The @code{keymap-global-set} command reads the command name after the
|
||||
key. After you press the key, a message like this appears so that you
|
||||
can confirm that you are binding the key you want:
|
||||
|
||||
|
|
@ -1802,7 +1802,7 @@ reads another character; if that is @kbd{4}, another prefix character,
|
|||
it reads one more character, and so on. For example,
|
||||
|
||||
@example
|
||||
M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
|
||||
M-x keymap-global-set @key{RET} C-x 4 $ spell-other-window @key{RET}
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
|
|
@ -1810,8 +1810,8 @@ redefines @kbd{C-x 4 $} to run the (fictitious) command
|
|||
@code{spell-other-window}.
|
||||
|
||||
You can remove the global definition of a key with
|
||||
@code{global-unset-key}. This makes the key @dfn{undefined}; if you
|
||||
type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
|
||||
@code{keymap-global-unset}. This makes the key @dfn{undefined}; if you
|
||||
type it, Emacs will just beep. Similarly, @code{keymap-local-unset} makes
|
||||
a key undefined in the current major mode keymap, which makes the global
|
||||
definition (or lack of one) come back into effect in that major mode.
|
||||
|
||||
|
|
@ -1844,11 +1844,11 @@ you can specify them in your initialization file by writing Lisp code.
|
|||
simplest is to use the @code{kbd} function, which converts a textual
|
||||
representation of a key sequence---similar to how we have written key
|
||||
sequences in this manual---into a form that can be passed as an
|
||||
argument to @code{global-set-key}. For example, here's how to bind
|
||||
argument to @code{keymap-global-set}. For example, here's how to bind
|
||||
@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
|
||||
|
||||
@example
|
||||
(global-set-key (kbd "C-z") 'shell)
|
||||
(keymap-global-set "C-z" 'shell)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
|
|
@ -1861,69 +1861,24 @@ causes an error; it certainly isn't what you want.
|
|||
and mouse events:
|
||||
|
||||
@example
|
||||
(global-set-key (kbd "C-c y") 'clipboard-yank)
|
||||
(global-set-key (kbd "C-M-q") 'query-replace)
|
||||
(global-set-key (kbd "<f5>") 'flyspell-mode)
|
||||
(global-set-key (kbd "C-<f5>") 'display-line-numbers-mode)
|
||||
(global-set-key (kbd "C-<right>") 'forward-sentence)
|
||||
(global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
|
||||
@end example
|
||||
|
||||
Instead of using @code{kbd}, you can use a Lisp string or vector to
|
||||
specify the key sequence. Using a string is simpler, but only works
|
||||
for @acronym{ASCII} characters and Meta-modified @acronym{ASCII}
|
||||
characters. For example, here's how to bind @kbd{C-x M-l} to
|
||||
@code{make-symbolic-link} (@pxref{Copying and Naming}):
|
||||
|
||||
@example
|
||||
(global-set-key "\C-x\M-l" 'make-symbolic-link)
|
||||
@end example
|
||||
|
||||
To bind a key sequence including @key{TAB}, @key{RET}, @key{ESC}, or
|
||||
@key{DEL}, the string should contain the Emacs Lisp escape sequence
|
||||
@samp{\t}, @samp{\r}, @samp{\e}, or @samp{\d} respectively. Here is
|
||||
an example which binds @kbd{C-x @key{TAB}} to @code{indent-rigidly}
|
||||
(@pxref{Indentation}):
|
||||
|
||||
@example
|
||||
(global-set-key "\C-x\t" 'indent-rigidly)
|
||||
@end example
|
||||
|
||||
When the key sequence includes function keys or mouse button events,
|
||||
or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a},
|
||||
you can use a vector to specify the key sequence. Each element in the
|
||||
vector stands for an input event; the elements are separated by spaces
|
||||
and surrounded by a pair of square brackets. If a vector element is a
|
||||
character, write it as a Lisp character constant: @samp{?} followed by
|
||||
the character as it would appear in a string. Function keys are
|
||||
represented by symbols (@pxref{Function Keys}); simply write the
|
||||
symbol's name, with no other delimiters or punctuation. Here are some
|
||||
examples:
|
||||
|
||||
@example
|
||||
(global-set-key [?\C-=] 'make-symbolic-link)
|
||||
(global-set-key [?\M-\C-=] 'make-symbolic-link)
|
||||
(global-set-key [?\H-a] 'make-symbolic-link)
|
||||
(global-set-key [f7] 'make-symbolic-link)
|
||||
(global-set-key [C-mouse-1] 'make-symbolic-link)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
You can use a vector for the simple cases too:
|
||||
|
||||
@example
|
||||
(global-set-key [?\C-z ?\M-l] 'make-symbolic-link)
|
||||
(keymap-global-set "C-c y" 'clipboard-yank)
|
||||
(keymap-global-set "C-M-q" 'query-replace)
|
||||
(keymap-global-set "<f5>" 'flyspell-mode)
|
||||
(keymap-global-set "C-<f5>" 'display-line-numbers-mode)
|
||||
(keymap-global-set "C-<right>" 'forward-sentence)
|
||||
(keymap-global-set "<mouse-2>" 'mouse-save-then-kill)
|
||||
@end example
|
||||
|
||||
Language and coding systems may cause problems with key bindings for
|
||||
non-@acronym{ASCII} characters. @xref{Init Non-ASCII}.
|
||||
|
||||
@findex define-key
|
||||
@findex keymap-set
|
||||
@findex keymap-unset
|
||||
As described in @ref{Local Keymaps}, major modes and minor modes can
|
||||
define local keymaps. These keymaps are constructed when the mode is
|
||||
loaded for the first time in a session. The function @code{define-key}
|
||||
can be used to make changes in a specific keymap. This function can
|
||||
also unset keys, when passed @code{nil} as the binding.
|
||||
loaded for the first time in a session. The function @code{keymap-set}
|
||||
can be used to make changes in a specific keymap. To remove a key
|
||||
binding, use @code{keymap-unset}.
|
||||
|
||||
Since a mode's keymaps are not constructed until it has been loaded,
|
||||
you must delay running code which modifies them, e.g., by putting it
|
||||
|
|
@ -1935,11 +1890,11 @@ the one for @kbd{C-c C-x x} in Texinfo mode:
|
|||
@example
|
||||
(add-hook 'texinfo-mode-hook
|
||||
(lambda ()
|
||||
(define-key texinfo-mode-map "\C-cp"
|
||||
(keymap-set texinfo-mode-map "C-c p"
|
||||
'backward-paragraph)
|
||||
(define-key texinfo-mode-map "\C-cn"
|
||||
(keymap-set texinfo-mode-map "C-c n"
|
||||
'forward-paragraph)))
|
||||
(define-key texinfo-mode-map "\C-c\C-xx" nil)
|
||||
(keymap-set texinfo-mode-map "C-c C-x x" nil)
|
||||
@end example
|
||||
|
||||
@node Modifier Keys
|
||||
|
|
@ -1961,7 +1916,7 @@ between those keystrokes. However, you can bind shifted @key{Control}
|
|||
alphabetical keystrokes in GUI frames:
|
||||
|
||||
@lisp
|
||||
(global-set-key (kbd "C-S-n") #'previous-line)
|
||||
(keymap-global-set "C-S-n" #'previous-line)
|
||||
@end lisp
|
||||
|
||||
For all other modifiers, you can make the modified alphabetical
|
||||
|
|
@ -2115,7 +2070,7 @@ button, @code{mouse-2} for the next, and so on. Here is how you can
|
|||
redefine the second mouse button to split the current window:
|
||||
|
||||
@example
|
||||
(global-set-key [mouse-2] 'split-window-below)
|
||||
(keymap-global-set "<mouse-2>" 'split-window-below)
|
||||
@end example
|
||||
|
||||
The symbols for drag events are similar, but have the prefix
|
||||
|
|
@ -2198,7 +2153,7 @@ Thus, here is how to define the command for clicking the first button in
|
|||
a mode line to run @code{scroll-up-command}:
|
||||
|
||||
@example
|
||||
(global-set-key [mode-line mouse-1] 'scroll-up-command)
|
||||
(keymap-global-set "<mode-line> <mouse-1>" 'scroll-up-command)
|
||||
@end example
|
||||
|
||||
Here is the complete list of these dummy prefix keys and their
|
||||
|
|
@ -2589,13 +2544,13 @@ Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
|
|||
(@pxref{Init Rebinding}).
|
||||
|
||||
@example
|
||||
(global-set-key "\C-xl" 'make-symbolic-link)
|
||||
(keymap-global-set "C-x l" 'make-symbolic-link)
|
||||
@end example
|
||||
|
||||
or
|
||||
|
||||
@example
|
||||
(define-key global-map "\C-xl" 'make-symbolic-link)
|
||||
(keymap-set global-map "C-x l" 'make-symbolic-link)
|
||||
@end example
|
||||
|
||||
Note once again the single-quote used to refer to the symbol
|
||||
|
|
@ -2605,7 +2560,7 @@ Note once again the single-quote used to refer to the symbol
|
|||
Do the same thing for Lisp mode only.
|
||||
|
||||
@example
|
||||
(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
|
||||
(keymap-set lisp-mode-map "C-x l" 'make-symbolic-link)
|
||||
@end example
|
||||
|
||||
@item
|
||||
|
|
@ -2622,7 +2577,7 @@ so that they run @code{forward-line} instead.
|
|||
Make @kbd{C-x C-v} undefined.
|
||||
|
||||
@example
|
||||
(global-unset-key "\C-x\C-v")
|
||||
(keymap-global-unset "C-x C-v")
|
||||
@end example
|
||||
|
||||
One reason to undefine a key is so that you can make it a prefix.
|
||||
|
|
@ -2798,18 +2753,6 @@ strings incorrectly. You should then avoid adding Emacs Lisp code
|
|||
that modifies the coding system in other ways, such as calls to
|
||||
@code{set-language-environment}.
|
||||
|
||||
To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init
|
||||
Rebinding}). The string syntax cannot be used, since the
|
||||
non-@acronym{ASCII} characters will be interpreted as meta keys. For
|
||||
instance:
|
||||
|
||||
@example
|
||||
(global-set-key [?@var{char}] 'some-function)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.
|
||||
|
||||
@node Early Init File
|
||||
@subsection The Early Init File
|
||||
@cindex early init file
|
||||
|
|
|
|||
|
|
@ -439,7 +439,7 @@ name to execute the last keyboard macro, in its current form. (If you
|
|||
later add to the definition of this macro, that does not alter the
|
||||
name's definition as a macro.) The macro name is a Lisp symbol, and
|
||||
defining it in this way makes it a valid command name for calling with
|
||||
@kbd{M-x} or for binding a key to with @code{global-set-key}
|
||||
@kbd{M-x} or for binding a key to with @code{keymap-global-set}
|
||||
(@pxref{Keymaps}). If you specify a name that has a prior definition
|
||||
other than a keyboard macro, an error message is shown and nothing is
|
||||
changed.
|
||||
|
|
|
|||
|
|
@ -451,7 +451,7 @@ reads and discards the following up-event. You can get access to that
|
|||
up-event with the @samp{U} code character.
|
||||
|
||||
This kind of input is used by commands such as @code{describe-key} and
|
||||
@code{global-set-key}.
|
||||
@code{keymap-global-set}.
|
||||
|
||||
@item K
|
||||
A key sequence on a form that can be used as input to functions like
|
||||
|
|
@ -2147,7 +2147,7 @@ bind it to the @code{signal usr1} event sequence:
|
|||
(defun usr1-handler ()
|
||||
(interactive)
|
||||
(message "Got USR1 signal"))
|
||||
(global-set-key [signal usr1] 'usr1-handler)
|
||||
(keymap-global-set "<signal> <usr1>" 'usr1-handler)
|
||||
@end smallexample
|
||||
|
||||
@node Classifying Events
|
||||
|
|
@ -3016,7 +3016,7 @@ supplied to input methods (@pxref{Input Methods}). Use
|
|||
if you want to translate characters after input methods operate.
|
||||
@end defvar
|
||||
|
||||
@defun keyboard-translate from to
|
||||
@defun key-translate from to
|
||||
This function modifies @code{keyboard-translate-table} to translate
|
||||
character code @var{from} into character code @var{to}. It creates
|
||||
the keyboard translate table if necessary.
|
||||
|
|
@ -3027,12 +3027,12 @@ make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
|
|||
operations:
|
||||
|
||||
@example
|
||||
(keyboard-translate ?\C-x 'control-x)
|
||||
(keyboard-translate ?\C-c 'control-c)
|
||||
(keyboard-translate ?\C-v 'control-v)
|
||||
(global-set-key [control-x] 'kill-region)
|
||||
(global-set-key [control-c] 'kill-ring-save)
|
||||
(global-set-key [control-v] 'yank)
|
||||
(key-translate "C-x" "<control-x>")
|
||||
(key-translate "C-c" "<control-c>")
|
||||
(key-translate "C-v" "<control-v>")
|
||||
(keymap-global-set "<control-x>" 'kill-region)
|
||||
(keymap-global-set "<control-c>" 'kill-ring-save)
|
||||
(keymap-global-set "<control-v>" 'yank)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
|
|
|
|||
|
|
@ -840,6 +840,7 @@ Keymaps
|
|||
* Key Lookup:: Finding a key's binding in one keymap.
|
||||
* Functions for Key Lookup:: How to request key lookup.
|
||||
* Changing Key Bindings:: Redefining a key in a keymap.
|
||||
* Low-Level Key Binding:: Legacy key syntax description.
|
||||
* Remapping Commands:: A keymap can translate one command to another.
|
||||
* Translation Keymaps:: Keymaps for translating sequences of events.
|
||||
* Key Binding Commands:: Interactive interfaces for redefining keys.
|
||||
|
|
|
|||
|
|
@ -30,6 +30,7 @@ is found. The whole process is called @dfn{key lookup}.
|
|||
* Key Lookup:: Finding a key's binding in one keymap.
|
||||
* Functions for Key Lookup:: How to request key lookup.
|
||||
* Changing Key Bindings:: Redefining a key in a keymap.
|
||||
* Low-Level Key Binding:: Legacy key syntax description.
|
||||
* Remapping Commands:: A keymap can translate one command to another.
|
||||
* Translation Keymaps:: Keymaps for translating sequences of events.
|
||||
* Key Binding Commands:: Interactive interfaces for redefining keys.
|
||||
|
|
@ -95,21 +96,11 @@ Manual}.
|
|||
(kbd "C-M-<down>") @result{} [C-M-down]
|
||||
@end example
|
||||
|
||||
@findex kbd-valid-p
|
||||
@findex key-valid-p
|
||||
The @code{kbd} function is very permissive, and will try to return
|
||||
something sensible even if the syntax used isn't completely
|
||||
conforming. To check whether the syntax is actually valid, use the
|
||||
@code{kbd-valid-p} function.
|
||||
|
||||
@code{define-key} also supports using the shorthand syntax
|
||||
@samp{["..."]} syntax to define a key. The string has to be a
|
||||
strictly valid @code{kbd} sequence, and if it's not valid, an error
|
||||
will be signalled. For instance, to bind @key{C-c f}, you can say:
|
||||
|
||||
@lisp
|
||||
(define-key global-map ["C-c f"] #'find-file-literally)
|
||||
@end lisp
|
||||
|
||||
@code{key-valid-p} function.
|
||||
@end defun
|
||||
|
||||
|
||||
|
|
@ -627,16 +618,16 @@ active keymap.
|
|||
@result{} nil
|
||||
@end group
|
||||
@group
|
||||
(local-set-key "\C-p" ctl-x-map)
|
||||
(keymap-local-set "C-p" ctl-x-map)
|
||||
@result{} nil
|
||||
@end group
|
||||
@group
|
||||
(key-binding "\C-p\C-f")
|
||||
(keymap-binding "C-p C-f")
|
||||
@result{} find-file
|
||||
@end group
|
||||
|
||||
@group
|
||||
(key-binding "\C-p6")
|
||||
(keymap-binding "C-p 6")
|
||||
@result{} nil
|
||||
@end group
|
||||
@end example
|
||||
|
|
@ -699,7 +690,7 @@ use, in place of the buffer's default local keymap.
|
|||
@cindex major mode keymap
|
||||
The local keymap is normally set by the buffer's major mode, and
|
||||
every buffer with the same major mode shares the same local keymap.
|
||||
Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands})
|
||||
Hence, if you call @code{keymap-local-set} (@pxref{Key Binding Commands})
|
||||
to change the local keymap in one buffer, that also affects the local
|
||||
keymaps in other buffers with the same major mode.
|
||||
|
||||
|
|
@ -733,39 +724,7 @@ Normally it ignores @code{overriding-local-map} and
|
|||
then it pays attention to them. @var{position} can optionally be either
|
||||
an event position as returned by @code{event-start} or a buffer
|
||||
position, and may change the keymaps as described for
|
||||
@code{key-binding}.
|
||||
@end defun
|
||||
|
||||
@defun key-binding key &optional accept-defaults no-remap position
|
||||
This function returns the binding for @var{key} according to the
|
||||
current active keymaps. The result is @code{nil} if @var{key} is
|
||||
undefined in the keymaps.
|
||||
|
||||
The argument @var{accept-defaults} controls checking for default
|
||||
bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}).
|
||||
|
||||
When commands are remapped (@pxref{Remapping Commands}),
|
||||
@code{key-binding} normally processes command remappings so as to
|
||||
return the remapped command that will actually be executed. However,
|
||||
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
|
||||
remappings and returns the binding directly specified for @var{key}.
|
||||
|
||||
If @var{key} starts with a mouse event (perhaps following a prefix
|
||||
event), the maps to be consulted are determined based on the event's
|
||||
position. Otherwise, they are determined based on the value of point.
|
||||
However, you can override either of them by specifying @var{position}.
|
||||
If @var{position} is non-@code{nil}, it should be either a buffer
|
||||
position or an event position like the value of @code{event-start}.
|
||||
Then the maps consulted are determined based on @var{position}.
|
||||
|
||||
Emacs signals an error if @var{key} is not a string or a vector.
|
||||
|
||||
@example
|
||||
@group
|
||||
(key-binding "\C-x\C-f")
|
||||
@result{} find-file
|
||||
@end group
|
||||
@end example
|
||||
@code{keymap-binding}.
|
||||
@end defun
|
||||
|
||||
@node Searching Keymaps
|
||||
|
|
@ -1042,7 +1001,7 @@ keymap.
|
|||
Let's use the term @dfn{keymap entry} to describe the value found by
|
||||
looking up an event type in a keymap. (This doesn't include the item
|
||||
string and other extra elements in a keymap element for a menu item, because
|
||||
@code{lookup-key} and other key lookup functions don't include them in
|
||||
@code{keymap-lookup} and other key lookup functions don't include them in
|
||||
the returned value.) While any Lisp object may be stored in a keymap
|
||||
as a keymap entry, not all make sense for key lookup. Here is a table
|
||||
of the meaningful types of keymap entries:
|
||||
|
|
@ -1193,7 +1152,7 @@ Used in keymaps to undefine keys. It calls @code{ding}, but does
|
|||
not cause an error.
|
||||
@end deffn
|
||||
|
||||
@defun local-key-binding key &optional accept-defaults
|
||||
@defun keymap-local-binding key &optional accept-defaults
|
||||
This function returns the binding for @var{key} in the current
|
||||
local keymap, or @code{nil} if it is undefined there.
|
||||
|
||||
|
|
@ -1201,7 +1160,7 @@ 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
|
||||
@defun keymap-global-binding key &optional accept-defaults
|
||||
This function returns the binding for command @var{key} in the
|
||||
current global keymap, or @code{nil} if it is undefined there.
|
||||
|
||||
|
|
@ -1284,65 +1243,55 @@ change a binding in the global keymap, the change is effective in all
|
|||
buffers (though it has no direct effect in buffers that shadow the
|
||||
global binding with a local one). If you change the current buffer's
|
||||
local map, that usually affects all buffers using the same major mode.
|
||||
The @code{global-set-key} and @code{local-set-key} functions are
|
||||
The @code{keymap-global-set} and @code{keymap-local-set} functions are
|
||||
convenient interfaces for these operations (@pxref{Key Binding
|
||||
Commands}). You can also use @code{define-key}, a more general
|
||||
Commands}). You can also use @code{keymap-set}, a more general
|
||||
function; then you must explicitly specify the map to change.
|
||||
|
||||
When choosing the key sequences for Lisp programs to rebind, please
|
||||
follow the Emacs conventions for use of various keys (@pxref{Key
|
||||
Binding Conventions}).
|
||||
|
||||
@cindex meta character key constants
|
||||
@cindex control character key constants
|
||||
@code{define-key} (and other functions that are used to rebind keys)
|
||||
understand a number of different syntaxes for the keys.
|
||||
The functions below signal an error if @var{keymap} is not a keymap,
|
||||
or if @var{key} is not a valid key.
|
||||
|
||||
@table @asis
|
||||
@item A vector containing a single string.
|
||||
This is the preferred way to represent a key sequence. Here's a
|
||||
couple of examples:
|
||||
@var{key} is a string representing a single key or a series of key
|
||||
strokes. Key strokes are separated by a single space character.
|
||||
|
||||
@example
|
||||
["C-c M-f"]
|
||||
["S-<home>"]
|
||||
@end example
|
||||
Each key stroke is either a single character, or the name of an
|
||||
event, surrounded by angle brackets. In addition, any key stroke
|
||||
may be preceded by one or more modifier keys. Finally, a limited
|
||||
number of characters have a special shorthand syntax. Here's some
|
||||
example key sequences:
|
||||
|
||||
The syntax is the same as the one used by Emacs when displaying key
|
||||
bindings, for instance in @samp{*Help*} buffers and help texts.
|
||||
@table @kbd
|
||||
@item f
|
||||
The key @kbd{f}.
|
||||
|
||||
If the syntax isn't valid, an error will be raised when running
|
||||
@code{define-key}, or when byte-compiling code that has these calls.
|
||||
@item S o m
|
||||
A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}.
|
||||
|
||||
@item A vector containing lists of keys.
|
||||
You can use a list containing modifier names plus one base event (a
|
||||
character or function key name). For example, @code{[(control ?a)
|
||||
(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control
|
||||
left)]} is equivalent to @kbd{C-H-left}.
|
||||
@item C-c o
|
||||
A two key sequence of the keys @kbd{c} with the control modifier and
|
||||
then the key @kbd{o}
|
||||
|
||||
@item A string with control and meta characters.
|
||||
Internally, key sequences are often represented as strings using the
|
||||
special escape sequences for control and meta characters
|
||||
(@pxref{String Type}), but this representation can also be used by
|
||||
users when rebinding keys. A string like @code{"\M-x"} is read as
|
||||
containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a
|
||||
single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both
|
||||
read as containing a single @kbd{C-M-x}.
|
||||
@item H-<left>
|
||||
The key named @kbd{left} with the hyper modifier.
|
||||
|
||||
@item a vector of characters.
|
||||
This is the other internal representation of key sequences, and
|
||||
supports a fuller range of modifiers than the string representation.
|
||||
One example is @samp{[?\C-\H-x home]}, which represents the @kbd{C-H-x
|
||||
home} key sequence. @xref{Character Type}.
|
||||
@item M-RET
|
||||
The @kbd{return} key with a meta modifier.
|
||||
|
||||
@item C-M-<space>
|
||||
The @kbd{space} key with both the control and meta modifiers.
|
||||
@end table
|
||||
|
||||
The functions below signal an error if @var{keymap} is not a keymap,
|
||||
or if @var{key} is not a string or vector representing a key sequence.
|
||||
You can use event types (symbols) as shorthand for events that are
|
||||
lists. The @code{kbd} function (@pxref{Key Sequences}) is a
|
||||
convenient way to specify the key sequence.
|
||||
The only keys that have a special shorthand syntax are @kbd{NUL},
|
||||
@kbd{RET}, @kbd{TAB}, @kbd{LFD}, @kbd{ESC}, @kbd{SPC} and @kbd{DEL}.
|
||||
|
||||
@defun define-key keymap key binding
|
||||
The modifiers have to be specified in alphabetical order:
|
||||
@samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}.
|
||||
|
||||
@defun keymap-set keymap key binding
|
||||
This function sets the binding for @var{key} in @var{keymap}. (If
|
||||
@var{key} is more than one event long, the change is actually made
|
||||
in another keymap reached from @var{keymap}.) The argument
|
||||
|
|
@ -1350,7 +1299,7 @@ in another keymap reached from @var{keymap}.) The argument
|
|||
meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
|
||||
The value returned by @code{define-key} is @var{binding}.
|
||||
|
||||
If @var{key} is @code{[t]}, this sets the default binding in
|
||||
If @var{key} is @kbd{<t>}, this sets the default binding in
|
||||
@var{keymap}. When an event has no binding of its own, the Emacs
|
||||
command loop uses the keymap's default binding, if there is one.
|
||||
|
||||
|
|
@ -1358,7 +1307,7 @@ command loop uses the keymap's default binding, if there is one.
|
|||
@cindex key sequence error
|
||||
Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
|
||||
or undefined; otherwise an error is signaled. If some prefix of
|
||||
@var{key} is undefined, then @code{define-key} defines it as a prefix
|
||||
@var{key} is undefined, then @code{keymap-set} defines it as a prefix
|
||||
key so that the rest of @var{key} can be defined as specified.
|
||||
|
||||
If there was previously no binding for @var{key} in @var{keymap}, the
|
||||
|
|
@ -1376,7 +1325,7 @@ bindings in it:
|
|||
@result{} (keymap)
|
||||
@end group
|
||||
@group
|
||||
(define-key map ["C-f"] 'forward-char)
|
||||
(keymap-set map "C-f" 'forward-char)
|
||||
@result{} forward-char
|
||||
@end group
|
||||
@group
|
||||
|
|
@ -1386,7 +1335,7 @@ map
|
|||
|
||||
@group
|
||||
;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
|
||||
(define-key map ["C-x f"] 'forward-word)
|
||||
(keymap-set map "C-x f" 'forward-word)
|
||||
@result{} forward-word
|
||||
@end group
|
||||
@group
|
||||
|
|
@ -1399,14 +1348,14 @@ map
|
|||
|
||||
@group
|
||||
;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
|
||||
(define-key map ["C-p"] ctl-x-map)
|
||||
(keymap-set map "C-p" ctl-x-map)
|
||||
;; @code{ctl-x-map}
|
||||
@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
|
||||
@end group
|
||||
|
||||
@group
|
||||
;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
|
||||
(define-key map ["C-p C-f"] 'foo)
|
||||
(keymap-set map "C-p C-f" 'foo)
|
||||
@result{} 'foo
|
||||
@end group
|
||||
@group
|
||||
|
|
@ -1426,9 +1375,9 @@ changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
|
|||
default global map.
|
||||
|
||||
@defun define-keymap &key options... &rest pairs...
|
||||
@code{define-key} is the general work horse for defining a key in a
|
||||
@code{keymap-set} is the general work horse for defining a key in a
|
||||
keymap. When writing modes, however, you frequently have to bind a
|
||||
large number of keys at once, and using @code{define-key} on them all
|
||||
large number of keys at once, and using @code{keymap-set} on them all
|
||||
can be tedious and error-prone. Instead you can use
|
||||
@code{define-keymap}, which creates a keymaps and binds a number of
|
||||
keys. Here's a very basic example:
|
||||
|
|
@ -1437,14 +1386,14 @@ keys. Here's a very basic example:
|
|||
(define-keymap
|
||||
"n" #'forward-line
|
||||
"f" #'previous-line
|
||||
["C-c C-c"] #'quit-window)
|
||||
"C-c C-c" #'quit-window)
|
||||
@end lisp
|
||||
|
||||
This function creates a new sparse keymap, defines the two keystrokes
|
||||
in @var{pairs}, and returns the new keymap.
|
||||
|
||||
@var{pairs} is a list of alternating key bindings and key definitions,
|
||||
as accepted by @code{define-key}. In addition the key can be the
|
||||
as accepted by @code{keymap-set}. In addition the key can be the
|
||||
special symbol @code{:menu}, in which case the definition should be a
|
||||
menu definition as accepted by @code{easy-menu-define} (@pxref{Easy
|
||||
Menu}). Here's a brief example:
|
||||
|
|
@ -1513,8 +1462,8 @@ Here's an example:
|
|||
@lisp
|
||||
(defvar-keymap eww-textarea-map
|
||||
:parent text-mode-map
|
||||
"\r" #'forward-line
|
||||
[?\t] #'shr-next-link)
|
||||
"RET" #'forward-line
|
||||
"TAB" #'shr-next-link)
|
||||
@end lisp
|
||||
@end defmac
|
||||
|
||||
|
|
@ -1617,13 +1566,112 @@ Modes}); then its keymap will automatically inherit from
|
|||
(defvar special-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(suppress-keymap map)
|
||||
(define-key map "q" 'quit-window)
|
||||
(keymap-set map "q" 'quit-window)
|
||||
@dots{}
|
||||
map))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end defun
|
||||
|
||||
@node Low-Level Key Binding
|
||||
@section Low-Level Key Binding
|
||||
|
||||
Historically, Emacs has supported a number of different syntaxes for
|
||||
defining keys. The documented way to bind a key today is to use the
|
||||
syntax supported by @code{key-valid-p}, which is what all the
|
||||
functions like @code{keymap-set} and @code{keymap-lookup} supports.
|
||||
This section of the manual documents the old syntax and interface
|
||||
functions, and should not be used in new code.
|
||||
|
||||
@cindex meta character key constants
|
||||
@cindex control character key constants
|
||||
@code{define-key} (and other low-level functions that are used to
|
||||
rebind keys) understand a number of different syntaxes for the keys.
|
||||
|
||||
@table @asis
|
||||
@item A vector containing lists of keys.
|
||||
You can use a list containing modifier names plus one base event (a
|
||||
character or function key name). For example, @code{[(control ?a)
|
||||
(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control
|
||||
left)]} is equivalent to @kbd{C-H-left}.
|
||||
|
||||
@item A string with control and meta characters.
|
||||
Internally, key sequences are often represented as strings using the
|
||||
special escape sequences for control and meta characters
|
||||
(@pxref{String Type}), but this representation can also be used by
|
||||
users when rebinding keys. A string like @code{"\M-x"} is read as
|
||||
containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a
|
||||
single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both
|
||||
read as containing a single @kbd{C-M-x}.
|
||||
|
||||
@item a vector of characters.
|
||||
This is the other internal representation of key sequences, and
|
||||
supports a fuller range of modifiers than the string representation.
|
||||
One example is @samp{[?\C-\H-x home]}, which represents the @kbd{C-H-x
|
||||
home} key sequence. @xref{Character Type}.
|
||||
@end table
|
||||
|
||||
@defun define-key keymap key binding &optional remove
|
||||
This function is like @code{keymap-set} (@pxref{Changing Key
|
||||
Bindings}, but understands only the legacy key syntaxes.
|
||||
|
||||
In addition, this function also has a @var{remove} argument. If it is
|
||||
non-@code{nil}, the definition will be removed. This is almost the
|
||||
same as setting the definition to @code{nil}, but makes a difference
|
||||
if the @var{keymap} has a parent, and @var{key} is shadowing the same
|
||||
binding in the parent. With @var{remove}, subsequent lookups will
|
||||
return the binding in the parent, and with a nil @var{def}, the
|
||||
lookups will return @code{nil}.
|
||||
@end defun
|
||||
|
||||
There's a number of other legacy key definition functions. Below is a
|
||||
list of them, with the equivalent modern function to use instead.
|
||||
|
||||
@table @code
|
||||
@findex global-set-key
|
||||
@item global-set-key
|
||||
Use @code{keymap-global-set} instead.
|
||||
|
||||
@findex local-set-key
|
||||
@item local-set-key
|
||||
Use @code{keymap-local-set} instead.
|
||||
|
||||
@findex global-unset-key
|
||||
@item global-unset-key
|
||||
Use @code{keymap-global-unset} instead.
|
||||
|
||||
@findex local-unset-key
|
||||
@item local-unset-key
|
||||
Use @code{keymap-local-unset} instead.
|
||||
|
||||
@findex substitute-key-definition
|
||||
@item substitute-key-definition
|
||||
Use @code{keymap-substitute} instead.
|
||||
|
||||
@findex define-key-after
|
||||
@item define-key-after
|
||||
Use @code{keymap-set-after} instead.
|
||||
|
||||
@findex keyboard-translate
|
||||
@item keyboard-translate
|
||||
Use @code{key-translate} instead.
|
||||
|
||||
@findex lookup-keymap
|
||||
@findex key-binding
|
||||
@item lookup-keymap
|
||||
@itemx key-binding
|
||||
Use @code{keymap-lookup} instead.
|
||||
|
||||
@findex local-key-binding
|
||||
@item local-key-binding
|
||||
Use @code{keymap-local-lookup} instead.
|
||||
|
||||
@findex global-key-binding
|
||||
@item gobal-key-binding
|
||||
Use @code{keymap-global-lookup} instead.
|
||||
@end table
|
||||
|
||||
|
||||
@node Remapping Commands
|
||||
@section Remapping Commands
|
||||
@cindex remapping commands
|
||||
|
|
@ -1834,32 +1882,18 @@ problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really
|
|||
This section describes some convenient interactive interfaces for
|
||||
changing key bindings. They work by calling @code{define-key}.
|
||||
|
||||
People often use @code{global-set-key} in their init files
|
||||
People often use @code{keymap-global-set} in their init files
|
||||
(@pxref{Init File}) for simple customization. For example,
|
||||
|
||||
@smallexample
|
||||
(global-set-key (kbd "C-x C-\\") 'next-line)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
or
|
||||
|
||||
@smallexample
|
||||
(global-set-key [?\C-x ?\C-\\] 'next-line)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
or
|
||||
|
||||
@smallexample
|
||||
(global-set-key [(control ?x) (control ?\\)] 'next-line)
|
||||
(keymap-global-set "C-x C-\\" 'next-line)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
redefines @kbd{C-x C-\} to move down a line.
|
||||
|
||||
@smallexample
|
||||
(global-set-key [M-mouse-1] 'mouse-set-point)
|
||||
(keymap-global-set "M-<mouse-1>" 'mouse-set-point)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
|
|
@ -1873,14 +1907,7 @@ they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
|
|||
must type the keys as multibyte too. For instance, if you use this:
|
||||
|
||||
@smallexample
|
||||
(global-set-key "ö" 'my-function) ; bind o-umlaut
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
or
|
||||
|
||||
@smallexample
|
||||
(global-set-key ?ö 'my-function) ; bind o-umlaut
|
||||
(keymap-global-set "ö" 'my-function) ; bind o-umlaut
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
|
|
@ -1891,20 +1918,20 @@ binding, you need to teach Emacs how to decode the keyboard by using an
|
|||
appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU
|
||||
Emacs Manual}).
|
||||
|
||||
@deffn Command global-set-key key binding
|
||||
@deffn Command keymap-global-set key binding
|
||||
This function sets the binding of @var{key} in the current global map
|
||||
to @var{binding}.
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
(global-set-key @var{key} @var{binding})
|
||||
(keymap-global-set @var{key} @var{binding})
|
||||
@equiv{}
|
||||
(define-key (current-global-map) @var{key} @var{binding})
|
||||
(keymap-set (current-global-map) @var{key} @var{binding})
|
||||
@end group
|
||||
@end smallexample
|
||||
@end deffn
|
||||
|
||||
@deffn Command global-unset-key key
|
||||
@deffn Command keymap-global-unset key
|
||||
@cindex unbinding keys
|
||||
This function removes the binding of @var{key} from the current
|
||||
global map.
|
||||
|
|
@ -1915,50 +1942,32 @@ that uses @var{key} as a prefix---which would not be allowed if
|
|||
|
||||
@smallexample
|
||||
@group
|
||||
(global-unset-key "\C-l")
|
||||
(keymap-global-unset "C-l")
|
||||
@result{} nil
|
||||
@end group
|
||||
@group
|
||||
(global-set-key "\C-l\C-l" 'redraw-display)
|
||||
(keymap-global-set "C-l C-l" 'redraw-display)
|
||||
@result{} nil
|
||||
@end group
|
||||
@end smallexample
|
||||
|
||||
This function is equivalent to using @code{define-key} as follows:
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
(global-unset-key @var{key})
|
||||
@equiv{}
|
||||
(define-key (current-global-map) @var{key} nil)
|
||||
@end group
|
||||
@end smallexample
|
||||
@end deffn
|
||||
|
||||
@deffn Command local-set-key key binding
|
||||
@deffn Command keymap-local-set key binding
|
||||
This function sets the binding of @var{key} in the current local
|
||||
keymap to @var{binding}.
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
(local-set-key @var{key} @var{binding})
|
||||
(keymap-local-set @var{key} @var{binding})
|
||||
@equiv{}
|
||||
(define-key (current-local-map) @var{key} @var{binding})
|
||||
(keymap-set (current-local-map) @var{key} @var{binding})
|
||||
@end group
|
||||
@end smallexample
|
||||
@end deffn
|
||||
|
||||
@deffn Command local-unset-key key
|
||||
@deffn Command keymap-local-unset key
|
||||
This function removes the binding of @var{key} from the current
|
||||
local map.
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
(local-unset-key @var{key})
|
||||
@equiv{}
|
||||
(define-key (current-local-map) @var{key} nil)
|
||||
@end group
|
||||
@end smallexample
|
||||
@end deffn
|
||||
|
||||
@node Scanning Keymaps
|
||||
|
|
@ -2813,9 +2822,9 @@ using an indirection through @code{tool-bar-map}.
|
|||
By default, the global map binds @code{[tool-bar]} as follows:
|
||||
|
||||
@example
|
||||
(global-set-key [tool-bar]
|
||||
`(menu-item ,(purecopy "tool bar") ignore
|
||||
:filter tool-bar-make-keymap))
|
||||
(keymap-global-set "<tool-bar>"
|
||||
`(menu-item ,(purecopy "tool bar") ignore
|
||||
:filter tool-bar-make-keymap))
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
|
|
|
|||
|
|
@ -1672,9 +1672,9 @@ see `dired-use-ls-dired' for more details.")
|
|||
(dired-goto-subdir current-dir)
|
||||
(dired current-dir)))))
|
||||
(define-keymap
|
||||
[mouse-2] click
|
||||
[follow-link] 'mouse-face
|
||||
["RET"] click))))
|
||||
"<mouse-2>" click
|
||||
"<follow-link>" 'mouse-face
|
||||
"RET" click))))
|
||||
(setq segment-start (point)))))))
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue