@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
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
(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:
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
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:
-
-@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
+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}.
+
+ 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
(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
@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
@group
(let ((map (make-sparse-keymap)))
(set-keymap-parent map <theirmap>)
- (define-key map ...)
+ (keymap-set map ...)
...)
@end group
@end example
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}.
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
@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
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
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
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
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
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
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
@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,
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
@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
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"
;; @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.")
@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
@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
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
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
@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})
(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
projects / emacs.git / commitdiff