Edit the lispref manual for define-key/keymap-set fallout
* doc/lispref/variables.texi (Tips for Defining): * doc/lispref/text.texi (Clickable Text): * doc/lispref/modes.texi (Derived Modes): (Example Major Modes): * doc/lispref/loading.texi (Autoload): (Hooks for Loading): * doc/lispref/keymaps.texi (Creating Keymaps): (Inheritance and Keymaps): (Controlling Active Maps): (Changing Key Bindings): (Low-Level Key Binding): (Remapping Commands): (Translation Keymaps): (Key Binding Commands): * doc/lispref/help.texi (Help Functions): * doc/lispref/display.texi (Abstract Display Example): * doc/lispref/commands.texi (Interactive Codes): (Keyboard Events): (Misc Events): (Classifying Events): (Strings of Events): Prefer `keymap-set' instead of `define-key' most places, and use `defvar-keymap' in some of the examples.
This commit is contained in:
Lars Ingebrigtsen
parent
50379fb78d
commit
1efc14561d
8 changed files with 71 additions and 116 deletions
|
|
@ -455,7 +455,7 @@ This kind of input is used by commands such as @code{describe-key} and
|
|||
|
||||
@item K
|
||||
A key sequence on a form that can be used as input to functions like
|
||||
@code{define-key}. This works like @samp{k}, except that it
|
||||
@code{keymap-set}. This works like @samp{k}, except that it
|
||||
suppresses, for the last input event in the key sequence, the
|
||||
conversions that are normally used (when necessary) to convert an
|
||||
undefined key into a defined one (@pxref{Key Sequence Input}), so this
|
||||
|
|
@ -1315,12 +1315,9 @@ actually treated as the meta key, not this.)
|
|||
It is best to avoid mentioning specific bit numbers in your program.
|
||||
To test the modifier bits of a character, use the function
|
||||
@code{event-modifiers} (@pxref{Classifying Events}). When making key
|
||||
bindings, you can use the read syntax for characters with modifier bits
|
||||
(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
|
||||
@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
|
||||
specify the characters (@pxref{Changing Key Bindings}). The function
|
||||
@code{event-convert-list} converts such a list into an event type
|
||||
(@pxref{Classifying Events}).
|
||||
bindings with @code{keymap-set}, you specify these events using
|
||||
strings like @samp{C-H-x} instead (for ``control hyper x'')
|
||||
(@pxref{Changing Key Bindings}).
|
||||
|
||||
@node Function Keys
|
||||
@subsection Function Keys
|
||||
|
|
@ -2078,7 +2075,7 @@ example:
|
|||
(interactive)
|
||||
(message "Caught signal %S" last-input-event))
|
||||
|
||||
(define-key special-event-map [sigusr1] 'sigusr-handler)
|
||||
(keymap-set special-event-map "<sigusr1>" 'sigusr-handler)
|
||||
@end smallexample
|
||||
|
||||
To test the signal handler, you can make Emacs send a signal to itself:
|
||||
|
|
@ -2284,21 +2281,6 @@ This function returns non-@code{nil} if @var{object} is a mouse movement
|
|||
event. @xref{Motion Events}.
|
||||
@end defun
|
||||
|
||||
@defun event-convert-list list
|
||||
This function converts a list of modifier names and a basic event type
|
||||
to an event type which specifies all of them. The basic event type
|
||||
must be the last element of the list. For example,
|
||||
|
||||
@example
|
||||
(event-convert-list '(control ?a))
|
||||
@result{} 1
|
||||
(event-convert-list '(control meta ?a))
|
||||
@result{} -134217727
|
||||
(event-convert-list '(control super f1))
|
||||
@result{} C-s-f1
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Accessing Mouse
|
||||
@subsection Accessing Mouse Events
|
||||
@cindex mouse events, data in
|
||||
|
|
@ -2518,25 +2500,14 @@ characters in a string is a complex matter, for reasons of historical
|
|||
compatibility, and it is not always possible.
|
||||
|
||||
We recommend that new programs avoid dealing with these complexities
|
||||
by not storing keyboard events in strings. Here is how to do that:
|
||||
by not storing keyboard events in strings containing control
|
||||
characters or the like, but instead store them in the common Emacs
|
||||
format as understood by @code{key-valid-p}.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Use vectors instead of strings for key sequences, when you plan to use
|
||||
them for anything other than as arguments to @code{lookup-key} and
|
||||
@code{define-key}. For example, you can use
|
||||
@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
|
||||
@code{this-command-keys-vector} instead of @code{this-command-keys}.
|
||||
|
||||
@item
|
||||
Use vectors to write key sequence constants containing meta characters,
|
||||
even when passing them directly to @code{define-key}.
|
||||
|
||||
@item
|
||||
When you have to look at the contents of a key sequence that might be a
|
||||
string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
|
||||
first, to convert it to a list.
|
||||
@end itemize
|
||||
If you read a key sequence with @code{read-key-sequence-vector} (or
|
||||
@code{read-key-sequence}), or access a key sequence with
|
||||
@code{this-command-keys-vector} (or @code{this-command-keys}), you can
|
||||
transform this to the recommended format by using @code{key-description}.
|
||||
|
||||
The complexities stem from the modifier bits that keyboard input
|
||||
characters can include. Aside from the Meta modifier, none of these
|
||||
|
|
|
|||
|
|
@ -7777,16 +7777,14 @@ The string is formatted #RRGGBB (hash followed by six hex digits)."
|
|||
(kill-buffer nil))
|
||||
|
||||
(setq colorcomp-mode-map
|
||||
(let ((m (make-sparse-keymap)))
|
||||
(suppress-keymap m)
|
||||
(define-key m "i" 'colorcomp-R-less)
|
||||
(define-key m "o" 'colorcomp-R-more)
|
||||
(define-key m "k" 'colorcomp-G-less)
|
||||
(define-key m "l" 'colorcomp-G-more)
|
||||
(define-key m "," 'colorcomp-B-less)
|
||||
(define-key m "." 'colorcomp-B-more)
|
||||
(define-key m " " 'colorcomp-copy-as-kill-and-exit)
|
||||
m))
|
||||
(define-keymap :suppress t
|
||||
"i" 'colorcomp-R-less
|
||||
"o" 'colorcomp-R-more
|
||||
"k" 'colorcomp-G-less
|
||||
"l" 'colorcomp-G-more
|
||||
"," 'colorcomp-B-less
|
||||
"." 'colorcomp-B-more
|
||||
"SPC" 'colorcomp-copy-as-kill-and-exit))
|
||||
@end smallexample
|
||||
|
||||
Note that we never modify the data in each node, which is fixed when the
|
||||
|
|
|
|||
|
|
@ -647,7 +647,7 @@ follows:
|
|||
|
||||
@smallexample
|
||||
@group
|
||||
(define-key global-map (string help-char) 'help-command)
|
||||
(keymap-set global-map (key-description (string help-char)) 'help-command)
|
||||
(fset 'help-command help-map)
|
||||
@end group
|
||||
@end smallexample
|
||||
|
|
|
|||
|
|
@ -367,7 +367,7 @@ I.e., something like:
|
|||
@group
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map <theirmap>)
|
||||
(define-key map ...)
|
||||
(keymap-set map ...)
|
||||
...)
|
||||
@end group
|
||||
@end example
|
||||
|
|
@ -420,10 +420,10 @@ The effect is that this keymap inherits all the bindings of
|
|||
but can add to them or override them with @var{elements}.
|
||||
|
||||
If you change the bindings in @var{parent-keymap} using
|
||||
@code{define-key} or other key-binding functions, these changed
|
||||
@code{keymap-set} or other key-binding functions, these changed
|
||||
bindings are visible in the inheriting keymap, unless shadowed by the
|
||||
bindings made by @var{elements}. The converse is not true: if you use
|
||||
@code{define-key} to change bindings in the inheriting keymap, these
|
||||
@code{keymap-set} to change bindings in the inheriting keymap, these
|
||||
changes are recorded in @var{elements}, but have no effect on
|
||||
@var{parent-keymap}.
|
||||
|
||||
|
|
@ -797,7 +797,7 @@ out with.
|
|||
This function returns the current global keymap. This is the same as
|
||||
the value of @code{global-map} unless you change one or the other.
|
||||
The return value is a reference, not a copy; if you use
|
||||
@code{define-key} or other functions on it you will alter global
|
||||
@code{keymap-set} or other functions on it you will alter global
|
||||
bindings.
|
||||
|
||||
@example
|
||||
|
|
@ -833,7 +833,7 @@ keymap.
|
|||
@end defun
|
||||
|
||||
@code{current-local-map} returns a reference to the local keymap, not
|
||||
a copy of it; if you use @code{define-key} or other functions on it
|
||||
a copy of it; if you use @code{keymap-set} or other functions on it
|
||||
you will alter local bindings.
|
||||
|
||||
@defun current-minor-mode-maps
|
||||
|
|
@ -1297,7 +1297,7 @@ This function sets the binding for @var{key} in @var{keymap}. (If
|
|||
in another keymap reached from @var{keymap}.) The argument
|
||||
@var{binding} can be any Lisp object, but only certain types are
|
||||
meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
|
||||
The value returned by @code{define-key} is @var{binding}.
|
||||
The value returned by @code{keymap-set} is @var{binding}.
|
||||
|
||||
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
|
||||
|
|
@ -1726,6 +1726,21 @@ The argument @var{accept-defaults} controls checking for default bindings,
|
|||
as in @code{lookup-key} (above).
|
||||
@end defun
|
||||
|
||||
@defun event-convert-list list
|
||||
This function converts a list of modifier names and a basic event type
|
||||
to an event type which specifies all of them. The basic event type
|
||||
must be the last element of the list. For example,
|
||||
|
||||
@example
|
||||
(event-convert-list '(control ?a))
|
||||
@result{} 1
|
||||
(event-convert-list '(control meta ?a))
|
||||
@result{} -134217727
|
||||
(event-convert-list '(control super f1))
|
||||
@result{} C-s-f1
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Remapping Commands
|
||||
@section Remapping Commands
|
||||
@cindex remapping commands
|
||||
|
|
@ -1744,7 +1759,7 @@ definition for a key binding).
|
|||
the following remapping:
|
||||
|
||||
@smallexample
|
||||
(define-key my-mode-map [remap kill-line] 'my-kill-line)
|
||||
(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
|
|
@ -1759,8 +1774,8 @@ In addition, remapping only works through a single level; in the
|
|||
following example,
|
||||
|
||||
@smallexample
|
||||
(define-key my-mode-map [remap kill-line] 'my-kill-line)
|
||||
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
|
||||
(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line)
|
||||
(keymap-set my-mode-map "<remap> <my-kill-line>" 'my-other-kill-line)
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
|
|
@ -1772,7 +1787,7 @@ remapped to @code{my-kill-line}; if an ordinary binding specifies
|
|||
To undo the remapping of a command, remap it to @code{nil}; e.g.,
|
||||
|
||||
@smallexample
|
||||
(define-key my-mode-map [remap kill-line] nil)
|
||||
(keymap-set my-mode-map "<remap> <kill-line>" nil)
|
||||
@end smallexample
|
||||
|
||||
@defun command-remapping command &optional position keymaps
|
||||
|
|
@ -1904,7 +1919,7 @@ to turn the character that follows into a Hyper character:
|
|||
symbol
|
||||
(cons symbol (cdr e)))))
|
||||
|
||||
(define-key local-function-key-map "\C-ch" 'hyperify)
|
||||
(keymap-set local-function-key-map "C-c h" 'hyperify)
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
|
@ -1934,7 +1949,7 @@ problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really
|
|||
@section Commands for Binding Keys
|
||||
|
||||
This section describes some convenient interactive interfaces for
|
||||
changing key bindings. They work by calling @code{define-key}.
|
||||
changing key bindings. They work by calling @code{keymap-set}.
|
||||
|
||||
People often use @code{keymap-global-set} in their init files
|
||||
(@pxref{Init File}) for simple customization. For example,
|
||||
|
|
|
|||
|
|
@ -552,7 +552,7 @@ An autoloaded keymap loads automatically during key lookup when a prefix
|
|||
key's binding is the symbol @var{function}. Autoloading does not occur
|
||||
for other kinds of access to the keymap. In particular, it does not
|
||||
happen when a Lisp program gets the keymap from the value of a variable
|
||||
and calls @code{define-key}; not even if the variable name is the same
|
||||
and calls @code{keymap-set}; not even if the variable name is the same
|
||||
symbol @var{function}.
|
||||
|
||||
@cindex function cell in autoload
|
||||
|
|
@ -1156,7 +1156,7 @@ You don't need to give a directory or extension in the file name
|
|||
@var{library}. Normally, you just give a bare file name, like this:
|
||||
|
||||
@example
|
||||
(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval))
|
||||
(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval))
|
||||
@end example
|
||||
|
||||
To restrict which files can trigger the evaluation, include a
|
||||
|
|
|
|||
|
|
@ -916,10 +916,8 @@ which in turn may have been changed in a mode hook.
|
|||
Here is a hypothetical example:
|
||||
|
||||
@example
|
||||
(defvar hypertext-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(define-key map [down-mouse-3] 'do-hyper-link)
|
||||
map))
|
||||
(defvar-keymap hypertext-mode-map
|
||||
"<down-mouse-3>" #'do-hyper-link)
|
||||
|
||||
(define-derived-mode hypertext-mode
|
||||
text-mode "Hypertext"
|
||||
|
|
@ -1344,11 +1342,9 @@ the conventions listed above:
|
|||
|
||||
;; @r{Create the keymap for this mode.}
|
||||
@group
|
||||
(defvar text-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(define-key map "\e\t" 'ispell-complete-word)
|
||||
@dots{}
|
||||
map)
|
||||
(defvar-keymap text-mode-map
|
||||
"C-M-i" #'ispell-complete-word
|
||||
@dots{})
|
||||
"Keymap for `text-mode'.
|
||||
Many other modes, such as `mail-mode', `outline-mode' and
|
||||
`indented-text-mode', inherit all the commands defined in this map.")
|
||||
|
|
@ -1421,13 +1417,11 @@ common. The following code sets up the common commands:
|
|||
|
||||
@smallexample
|
||||
@group
|
||||
(defvar lisp-mode-shared-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map prog-mode-map)
|
||||
(define-key map "\e\C-q" 'indent-sexp)
|
||||
(define-key map "\177" 'backward-delete-char-untabify)
|
||||
map)
|
||||
"Keymap for commands shared by all sorts of Lisp modes.")
|
||||
(defvar-keymap lisp-mode-shared-map
|
||||
:parent prog-mode-map
|
||||
:doc "Keymap for commands shared by all sorts of Lisp modes."
|
||||
"C-M-q" #'indent-sexp
|
||||
"DEL" #'backward-delete-char-untabify)
|
||||
@end group
|
||||
@end smallexample
|
||||
|
||||
|
|
@ -1436,16 +1430,12 @@ And here is the code to set up the keymap for Lisp mode:
|
|||
|
||||
@smallexample
|
||||
@group
|
||||
(defvar lisp-mode-map
|
||||
(let ((map (make-sparse-keymap))
|
||||
(menu-map (make-sparse-keymap "Lisp")))
|
||||
(set-keymap-parent map lisp-mode-shared-map)
|
||||
(define-key map "\e\C-x" 'lisp-eval-defun)
|
||||
(define-key map "\C-c\C-z" 'run-lisp)
|
||||
@dots{}
|
||||
map)
|
||||
"Keymap for ordinary Lisp mode.
|
||||
All commands in `lisp-mode-shared-map' are inherited by this map.")
|
||||
(defvar-keymap lisp-mode-map
|
||||
:doc "Keymap for ordinary Lisp mode.
|
||||
All commands in `lisp-mode-shared-map' are inherited by this map."
|
||||
:parent lisp-mode-shared-map
|
||||
"C-M-x" #'lisp-eval-defun
|
||||
"C-c C-z" #'run-lisp)
|
||||
@end group
|
||||
@end smallexample
|
||||
|
||||
|
|
|
|||
|
|
@ -4195,7 +4195,7 @@ position. The action code is always @code{t}.
|
|||
For example, here is how Info mode handles @key{mouse-1}:
|
||||
|
||||
@smallexample
|
||||
(define-key Info-mode-map [follow-link] 'mouse-face)
|
||||
(keymap-set Info-mode-map "<follow-link>" 'mouse-face)
|
||||
@end smallexample
|
||||
|
||||
@item a function
|
||||
|
|
@ -4208,9 +4208,9 @@ For example, here is how pcvs enables @kbd{mouse-1} to follow links on
|
|||
file names only:
|
||||
|
||||
@smallexample
|
||||
(define-key map [follow-link]
|
||||
(lambda (pos)
|
||||
(eq (get-char-property pos 'face) 'cvs-filename-face)))
|
||||
(keymap-set map "<follow-link>"
|
||||
(lambda (pos)
|
||||
(eq (get-char-property pos 'face) 'cvs-filename-face)))
|
||||
@end smallexample
|
||||
|
||||
@item anything else
|
||||
|
|
|
|||
|
|
@ -686,7 +686,7 @@ entire computation of the value into the @code{defvar}, like this:
|
|||
@example
|
||||
(defvar my-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(define-key map "\C-c\C-a" 'my-command)
|
||||
(keymap-set map "C-c C-a" 'my-command)
|
||||
@dots{}
|
||||
map)
|
||||
@var{docstring})
|
||||
|
|
@ -702,25 +702,6 @@ important if the user has run hooks to alter part of the contents
|
|||
(such as, to rebind keys). Third, evaluating the @code{defvar} form
|
||||
with @kbd{C-M-x} will reinitialize the map completely.
|
||||
|
||||
Putting so much code in the @code{defvar} form has one disadvantage:
|
||||
it puts the documentation string far away from the line which names the
|
||||
variable. Here's a safe way to avoid that:
|
||||
|
||||
@example
|
||||
(defvar my-mode-map nil
|
||||
@var{docstring})
|
||||
(unless my-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(define-key map "\C-c\C-a" 'my-command)
|
||||
@dots{}
|
||||
(setq my-mode-map map)))
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This has all the same advantages as putting the initialization inside
|
||||
the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
|
||||
each form, if you do want to reinitialize the variable.
|
||||
|
||||
@node Accessing Variables
|
||||
@section Accessing Variable Values
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue