diff options
| -rw-r--r-- | doc/lispref/keymaps.texi | 11 | ||||
| -rw-r--r-- | lisp/keymap.el | 58 |
2 files changed, 48 insertions, 21 deletions
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index bbf7138b5be..ab862e75bb5 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -2070,7 +2070,16 @@ 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{keymap-set}. +changing key bindings. They work by calling @code{keymap-set} +(@pxref{Changing key Bindings}). In interactive use, these commands +prompt for the argument @var{key} and expect the user to type a valid +key sequence; they also prompt for the @var{binding} of the key +sequence, and expect the name of a command (i.e., a symbol that +satisfies @code{commandp}, @pxref{Interactive Call}). When called +from Lisp, these commands expect @var{key} to be a string that +satisfies @code{key-valid-p} (@pxref{Key Sequences}), and +@var{binding} to be any Lisp object that is meaningful in a keymap +(@pxref{Key Lookup}). People often use @code{keymap-global-set} in their init files (@pxref{Init File}) for simple customization. For example, diff --git a/lisp/keymap.el b/lisp/keymap.el index dccc0a3cd31..cd06b830e0a 100644 --- a/lisp/keymap.el +++ b/lisp/keymap.el @@ -40,11 +40,12 @@ (defun keymap-set (keymap key definition) "Set KEY to DEFINITION in KEYMAP. KEY is a string that satisfies `key-valid-p'. +If DEFINITION is a string, it must also satisfy `key-valid-p'. DEFINITION is anything that can be a key's definition: nil (means key is undefined in this keymap), a command (a Lisp function suitable for interactive calling), - a string (treated as a keyboard macro), + a string (treated as a keyboard macro or a sequence of input events), a keymap (to define a prefix key), a symbol (when the key is looked up, the symbol will stand for its function definition, which should at that time be one of the above, @@ -67,10 +68,17 @@ DEFINITION is anything that can be a key's definition: (defun keymap-global-set (key command &optional interactive) "Give KEY a global binding as COMMAND. -COMMAND is the command definition to use; usually it is -a symbol naming an interactively-callable function. +When called interactively, KEY is a key sequence. When called from +Lisp, KEY is a string that must satisfy `key-valid-p'. -KEY is a string that satisfies `key-valid-p'. +COMMAND is the command definition to use. When called interactively, +this function prompts for COMMAND and accepts only names of known +commands, i.e., symbols that satisfy the `commandp' predicate. When +called from Lisp, COMMAND can be anything that `keymap-set' accepts +as its DEFINITION argument. + +If COMMAND is a string (which can only happen when this function is +callled from Lisp), it must satisfy `key-valid-p'. Note that if KEY has a local binding in the current buffer, that local binding will continue to shadow any global binding @@ -84,12 +92,19 @@ that you make with this function." (defun keymap-local-set (key command &optional interactive) "Give KEY a local binding as COMMAND. -COMMAND is the command definition to use; usually it is -a symbol naming an interactively-callable function. +When called interactively, KEY is a key sequence. When called from +Lisp, KEY is a string that must satisfy `key-valid-p'. -KEY is a string that satisfies `key-valid-p'. +COMMAND is the command definition to use. When called interactively, +this function prompts for COMMAND and accepts only names of known +commands, i.e., symbols that satisfy the `commandp' predicate. When +called from Lisp, COMMAND can be anything that `keymap-set' accepts +as its DEFINITION argument. -The binding goes in the current buffer's local map, which in most +If COMMAND is a string (which can only happen when this function is +callled from Lisp), it must satisfy `key-valid-p'. + +The binding goes in the current buffer's local keymap, which in most cases is shared with all other buffers in the same major mode." (declare (compiler-macro (lambda (form) (keymap--compile-check key) form)) (advertised-calling-convention (key command) "29.1")) @@ -103,10 +118,11 @@ cases is shared with all other buffers in the same major mode." (defun keymap-global-unset (key &optional remove) "Remove global binding of KEY (if any). -KEY is a string that satisfies `key-valid-p'. +When called interactively, KEY is a key sequence. When called from +Lisp, KEY is a string that satisfies `key-valid-p'. -If REMOVE (interactively, the prefix arg), remove the binding -instead of unsetting it. See `keymap-unset' for details." +If REMOVE is non-nil (interactively, the prefix arg), remove the +binding instead of unsetting it. See `keymap-unset' for details." (declare (compiler-macro (lambda (form) (keymap--compile-check key) form))) (interactive (list (key-description (read-key-sequence "Unset key globally: ")) @@ -115,10 +131,11 @@ instead of unsetting it. See `keymap-unset' for details." (defun keymap-local-unset (key &optional remove) "Remove local binding of KEY (if any). -KEY is a string that satisfies `key-valid-p'. +When called interactively, KEY is a key sequence. When called from +Lisp, KEY is a string that satisfies `key-valid-p'. -If REMOVE (interactively, the prefix arg), remove the binding -instead of unsetting it. See `keymap-unset' for details." +If REMOVE is non-nil (interactively, the prefix arg), remove the +binding instead of unsetting it. See `keymap-unset' for details." (declare (compiler-macro (lambda (form) (keymap--compile-check key) form))) (interactive (list (key-description (read-key-sequence "Unset key locally: ")) @@ -130,11 +147,11 @@ instead of unsetting it. See `keymap-unset' for details." "Remove key sequence KEY from KEYMAP. KEY is a string that satisfies `key-valid-p'. -If REMOVE, remove the binding instead of unsetting it. This only -makes a difference when there's a parent keymap. When unsetting -a key in a child map, it will still shadow the same key in the -parent keymap. Removing the binding will allow the key in the -parent keymap to be used." +If REMOVE is non-nil, remove the binding instead of unsetting it. +This only makes a difference when there's a parent keymap. When +unsetting a key in a child map, it will still shadow the same key +in the parent keymap. Removing the binding will allow the key in +the parent keymap to be used." (declare (compiler-macro (lambda (form) (keymap--compile-check key) form))) (keymap--check key) (define-key keymap (key-parse key) nil remove)) @@ -201,7 +218,8 @@ a menu, so this function is not useful for non-menu keymaps." (defun key-parse (keys) "Convert KEYS to the internal Emacs key representation. -See `kbd' for a descripion of KEYS." +KEYS should be a string describing a key sequence in the format +returned by \\[describe-key] (`describe-key')." (declare (pure t) (side-effect-free t)) ;; A pure function is expected to preserve the match data. (save-match-data |