⟦344581cd6⟧

TextFile

@setfilename ../info/keymaps
@node Keymaps, Major and Minor Modes, Command Loop, Top
@chapter Keymaps

  The bindings between keyboard input and commands are recorded in
data structures called @dfn{keymaps}.  Each binding in a keymap is
between an individual character and either another keymap or a
command.  When a character is bound to another keymap, the next
character in the key sequence is looked up in that keymap, and so on
until a command is found.  This process is called @dfn{key lookup}.

@menu
* Keymap Terms::	
* Creating Keymaps::	
* Key Lookup::	
* Prefix Keys::	
* Global and Local Keymaps::	
* Changing Key Bindings::	
@end menu

@node Keymap Terms, Creating Keymaps, Keymaps, Keymaps
@comment  node-name,  next,  previous,  up
@section Keymaps: Terminology

  A sequence of keyboard input characters, or @dfn{keystrokes} is called
a @dfn{key}.  Thus, a key is not necessarily a single character.

  A key is said to have a @dfn{key binding} if all the characters in
the sequence of keyboard input characters are bound; this is the case
when each character is bound to a keymap in which the rest of the key
is looked up.

  A @dfn{complete key} is one that is bound to a command.  A @dfn{prefix
key} is one that is bound to a keymap.  Therefore, any initial sequence
of a complete key is a prefix key.  But the characters that follow a
prefix key may or may not complete the key.  An @dfn{undefined key} is
one that is not bound to either a keymap or a command.  @xref{Prefix
Keys}, for a more details.

  Examples of complete keys are @samp{@kbd{X}},
@samp{@kbd{@key{RET}}}, and @samp{@kbd{C-x 4 C-f}}.  Examples of
prefix keys are @samp{@kbd{C-c}}, @samp{@kbd{C-x}}, and @samp{@kbd{C-x
4}}.  Examples of undefined keys are @samp{@kbd{C-x C-g}}, and
@samp{@kbd{C-c 3}}.

  At any one time, two primary keymaps are in use: the @dfn{global map},
which is available in all buffers, and the @dfn{local keymap}, which is
usually associated with a major mode.  The local keymap bindings shadow
(i.e., are used in place of) the corresponding global bindings.
@xref{Global and Local Keymaps}, for the details.

  Note that a command is any action that may be called interactively
(@pxref{Command Overview}), including keyboard macros (@pxref{Keyboard
Macros}).

@node Creating Keymaps, Key Lookup, Keymap Terms, Keymaps
@section Creating Keymaps
@cindex creating keymaps

  A keymap can be represented as one of two kinds of Lisp object: a vector or a
list.  A @dfn{full keymap} is a vector of length 128.  The binding for a
character in such a keymap is found by indexing into the vector with the
character as the index.  

A @dfn{sparse keymap} is a list whose @sc{car} is the symbol
@code{keymap}, and whose remaining elements are pairs of the form
@code{(@var{char} .@: @var{binding})}.  Such a list is called a
@dfn{sparse keymap} because most of the entries would be @code{nil} in
a full keymap.  Use a sparse keymap when you expect only a few
entries.  (Also, Emacs automatically creates sparse keymaps for
intermediate keymaps, when @code{define-key} requires them.)
@cindex @code{define-key} in sparse keymaps

@cindex meta characters
@kindex ESC
  Keymaps are only of length 128, and so are unable to handle @key{META}
characters, whose codes are from 128 to 255.  Instead, Emacs represents
a @key{META} character as a sequence of two characters, the first of
which is @key{ESC} (the usual value of @code{meta-prefix-char}).  Thus,
the key @kbd{M-a} is really represented as @kbd{@key{ESC} a}, and its
binding is found at the slot for @samp{a} in @code{esc-map}.@refill

For example, the Lisp mode keymap uses @kbd{C-c C-l} for the
@code{run-lisp} command, @kbd{M-C-q} for @code{indent-sexp}, and
@kbd{M-C-x} for @code{lisp-send-defun}.

@example
lisp-mode-map
@result{} 
(keymap 
 (9 . lisp-indent-line)                 ; @key{TAB}
 (127 . backward-delete-char-untabify)  ; @key{DEL}
 (3 keymap 
    (12 . run-lisp))                    ; @kbd{C-c C-l}
 (27 keymap 
     (17 . indent-sexp)                 ; @kbd{M-C-q}
     (24 . lisp-send-defun)))           ; @kbd{M-C-x} 
@end example

@defun keymapp object
  This function returns @code{t} if @var{object} is a keymap,
@code{nil} otherwise.  A keymap is either a vector of length 128, or a
list with the form @code{(keymap @var{pairs}@dots{})}, where
@var{pairs} is a series of pairs of the form @w{@code{(@var{char} .@:
@var{binding})}}.

@example
(keymapp '(keymap))
    @result{} t
(keymapp (current-global-map))
    @result{} t
@end example
@end defun

@defun make-keymap
  This function creates and returns a new full keymap (i.e., a vector
of length 128).  All entries in the keymap are @code{nil}, which means
that each command is undefined in this keymap.

@example
(make-keymap)
    @result{} [nil nil nil @dots{} nil nil]
@end example
@end defun

@defun make-sparse-keymap
  This function creates and returns a new sparse keymap with no entries.

@example
(make-sparse-keymap)
    @result{} (keymap)
@end example
@end defun

@defun copy-keymap keymap
  This function returns a copy of @var{keymap}.  Starting with Emacs
version 18.50, @code{copy-keymap} is done recursively so any keymaps
that are components of @var{keymap} are copied as well.

@example
(setq map (copy-keymap (current-local-map)))
@result{} (keymap
     (27 keymap         ; @r{(This implements @key{META} characters.)}
       (83 . center-paragraph)
       (115 . center-line))
     (9 . tab-to-tab-stop))

(eq map (current-local-map))
    @result{} nil
(equal map (current-local-map))
    @result{} t
@end example
@end defun

@node Key Lookup, Prefix Keys, Creating Keymaps, Keymaps
@section Key Lookup

  @dfn{Key lookup} is the process by which Emacs searches through keymaps to
find the non-keymap object bound to the key.  (Note that the key lookup
process should be distinguished from the process of calling the
command that is found by the key lookup.)

  There are several types of @dfn{keymap entry} that may appear in
either full or sparse keymaps.  Indeed, any Lisp object may appear in a
keymap, but only a few types of object have meaning either for looking
up keys or for calling commands.

  When Emacs looks up a key, the lookup process starts from a particular
keymap that is determined by Emacs's current mode.  Emacs uses each
character of the key in sequence, determining the binding of the
character.  If the binding of the character in the keymap is another
keymap, the next character in the key, if any, is used to lookup the
next object.  This process repeats until any non-keymap object is found;
that object is the result of the key lookup.  If the key is not long
enough to lead to a non-keymap object, then a keymap is the result of
the lookup.

  The recognized keymap entries and their meanings are listed below.  

@table @asis
@item @code{nil}
@cindex nil in keymap
As a special case, @code{nil} means that the characters used so far in the
lookup are undefined in this keymap.  A @code{nil} entry is also
returned if a sparse keymap has no binding for the character.

@item @var{keymap}
@cindex keymap in keymap
The characters used so far in the lookup are a prefix key.  Subsequent
characters are looked up starting in @var{keymap}, which may be full
or sparse.

@item @var{list}
@cindex list in keymap
The characters used so far in the lookup may or may not be a prefix
key, depending on the form of the list.

@itemize @bullet
@item
If the @sc{car} of @var{list} is the symbol @code{keymap},
then this is really a keymap entry and is used as described above.

@item
As a special case, if @var{list} looks like @w{@code{(@var{keymap} .@:
@var{char})}}, then the binding of @var{char} in the keymap called
@var{keymap} is used as if it had been the entry.  This permits you to
define one key as an alias for another key, so it uses whatever
definition the othr key has.

@item
@cindex @code{lambda} in keymap
If the @sc{car} of @var{list} is @code{lambda}, then this is a lambda
expression, which should be interactive.  It is the definition of the
key.
@end itemize

@item @var{string}
@cindex string in keymap
The @var{string} represents a keyboard macro.  When the characters
used so far in the lookup is entered as a command, the characters in
@var{string} are used as if they had been typed instead of the key.
(@pxref{Keyboard Macros}, for the details.)

@item @var{symbol}
@cindex symbol in keymap
The @var{symbol}'s function definition is found by dereferencing.
e@xref{Classifying Lists}, to find out how symbols are dereferenced.
One of the following objects should be found.

@itemize @bullet
@item
@cindex keymap in keymap
As a special case, if a keymap is found in the symbol's function cell,
it is used as if the entry had been that keymap.  A keymap is not a
function, so this symbol would not be valid in a function call.

@item
@cindex function in keymap
If a function is found, it is the result of the key lookup.  When the
key is entered, that function is called; it must be interactive.

@cindex @code{ignore} in keymap
@cindex @code{undefined} in keymap
@cindex invalid-function error
Two commands are available for special purposes: @code{ignore} and
@code{undefined}.

The command @code{ignore} means that the key does nothing
(@code{ignore} just returns @code{nil}).  The command @code{undefined}
means to treat the key as undefined; this command calls @code{ding} to
ring the bell, but does not cause an error.
@cindex preventing prefix key

@item
@cindex string in keymap
@cindex keyboard macro in keymap
If a string is found, it represents a keyboard macro, as above.

@item
If a list of the form @code{(@var{keymap} .@: @var{char})} is found, it
is @emph{not} used as if it had been the entry.  This sort of list is
meaningful only if it appears directly in the keymap.
@end itemize

@item @var{anything else}
If any other type of object is found, the lookup terminates.
@end table

  In short, a keymap entry may be another keymap, or a command.  Three
special cases are @code{nil}, meaning that the characters used so far
are undefined in this keymap; a list that starts with a keymap; and a
symbol with a keymap in the function cell.

@defun lookup-key keymap key
  This function returns the definition of @var{key} in @var{keymap}.  If
it returns a number, this means @var{key} is ``too long''; that is, the
characters fail to be a valid sequence in @var{keymap}.  The number is
how many characters at the front of @var{key} that compose a meaningful
key sequence.

  This function does not perform automatic downcasing as is done by
@code{read-key-sequence} (@pxref{Keyboard Input}).  All the other
functions described in this chapter that lookup keys use
@code{lookup-key}.

@example
(lookup-key (current-global-map) "\C-x\C-f")
    @result{} find-file
(lookup-key (current-global-map) "\C-x\C-f12345")
    @result{} 2
@end example
@end defun

@defun ignore &rest args
Ignore any arguments and return @code{nil}.  Used in keymaps to ignore
keys.
@end defun

@deffn Command undefined
@findex ding@r{, use of}
  Used in keymaps to undefine keys.  It calls @code{ding}, but does
not cause an error.
@end deffn

@node Prefix Keys, Global and Local Keymaps, Key Lookup, Keymaps
@section Prefix Keys
@cindex prefix keys

  A @dfn{prefix key} has an associated keymap which defines what to do with
key sequences that start with the prefix key.  For example,
@code{ctl-x-map} is the keymap used for characters following the prefix key
@kbd{C-x}.  The following keymaps are reached via the global keymap when
looking up the associated prefix key.

@itemize @bullet

@item
@kindex C-x
@vindex ctl-x-map
@kindex Control-X-prefix
@code{ctl-x-map} is the variable name for the map used for characters
that follow @kbd{C-x}.  This map is also in the function cell of
@code{Control-X-prefix}.

@item
@kindex C-x-4
@vindex ctl-x-4-map
@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.

@item
@kindex ESC
@vindex esc-map
@kindex ESC-prefix
@code{esc-map} is for characters that follow @key{ESC}.  Thus, all Meta
characters are actually defined by this map.  This map is also in the
function cell of @code{ESC-prefix}.

@item
@kindex C-h
@vindex help-map
@code{help-map} is used for characters that follow @kbd{C-h}.

@item
@kindex C-c
@vindex mode-specific-map
@code{mode-specific-map} is for characters that follow @kbd{C-c}.

@end itemize

  The binding of a prefix key is the keymap to use for looking up the
characters that follow the prefix key.  In many cases, the binding is to
a Lisp symbol whose function definition is a
keymap.  The effect is the same, but the use of a symbol doubles
as a description of what the prefix key
is for.  Thus, the binding of @kbd{C-x} is the symbol
@code{Control-X-prefix}, whose function definition is the keymap for
@kbd{C-x} commands.  This keymap is also the value of @code{ctl-x-map}.@refill

  Prefix key definitions of this sort can appear in either the global map
or a local map.  The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and
@key{ESC} as prefix keys appear in the global map, so these prefix keys are
always available.  Major modes can locally redefine a key as a prefix by
putting a prefix key definition for it in the local map.@refill

  If a key is defined as a prefix in both the local map and the global,
the two definitions are effectively merged: the commands defined in the
local map's prefix definition take priority; those not defined there are
taken from the global map.

  In this example, @kbd{C-p} is made a prefix key in the local keymap
(so that @kbd{C-p} is identical to @kbd{C-x}).  The binding for @kbd{C-p
C-f} is the function @code{find-file}, just like @kbd{C-x C-f}.  The key
sequence @kbd{C-p 6} is not found in either the local map or global map.

@example
(use-local-map (make-sparse-keymap))
    @result{} nil
(local-set-key "\C-p" ctl-x-map)
    @result{} nil
(key-binding "\C-p\C-f")
    @result{} find-file

(key-binding "\C-p6")
    @result{} nil
@end example

@defun define-prefix-command symbol
  This function defines @var{symbol} as a prefix command.  It creates a
full keymap and stores it as @var{symbol}'s function definition.  This
can be used to create a keymap that is used like the @code{ESC-prefix}
keymap.  It may be convenient to also store the keymap in
a variable.  This function returns @var{symbol}.

In version 19, both the function definition and value are set.

In 18.54, the function definition is set, but not the value.
@end defun

@defvar meta-prefix-char
@kindex ESC
  This global variable is the Meta-prefix character code.  Normally it
will be @key{ESC}, which has the value of the decimal integer 27.  It
is used when translating a meta-character to a two-character sequence
so it can be looked up in a keymap.

Thus, in the default configuration, typing @kbd{M-b} causes Emacs to
look up @kbd{@key{ESC} b} in the current keymap and this calls the
@code{backward-word} command.  However, if you set the value of
@code{meta-prefix-char} to 24, the code for @kbd{C-x},
typing @kbd{M-b} will cause Emacs to
look up @kbd{C-x b} when you type @kbd{M-b}; this will call the
@code{switch-to-buffer} command. 

@example
meta-prefix-char                    ; @r{The default value.}
     @result{} 27
(key-binding "\M-b")
     @result{} backward-word
?\C-x                               ; @r{The print representation}
     @result{} 24                          ; @r{of a character.}
(setq meta-prefix-char 24)
     @result{} 24      
(key-binding "\M-b")
     @result{} switch-to-buffer            ; @r{Now, typing @kbd{M-b} is}
                                    ; @r{like typing @kbd{C-x b}.}

(setq meta-prefix-char 27)          ; @r{Avoid confusion!}
     @result{} 27                          ; @r{Restore the default value!}
@end example
@end defvar

@node Global and Local Keymaps, Changing Key Bindings, Prefix Keys, Keymaps
@section Global and Local Keymaps

  The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}.  The variable
@code{global-map} holds this keymap.

  Each buffer may have another keymap, its @dfn{local keymap}, which
may contain new or overriding definitions for keys.  Each buffer
records which local keymap is used with it.

  Both the global and local keymaps are used to determine what command
to execute when a key is entered.  The key lookup proceeds as
described earlier (@pxref{Key Lookup}), but Emacs @emph{first}
searches for the key in the local map; if Emacs does not find a local
definition, Emacs then searches the global map.  

@cindex major mode keymap
  Since every buffer that uses the same major mode normally uses the
very same local keymap, it may appear as if the keymap is local to the
mode.  A change to the local keymap in one buffer (using
@code{define-key}, for example) will only be seen in other buffers that
use that keymap.

  The minibuffer has local keymaps, too; they contain various
completion and exit commands.  @xref{Minibuffers}.
@cindex minibuffer keymaps

@vindex c-mode-map
@vindex lisp-mode-map
  The local keymaps that are used for Lisp mode, C mode, and several
other major modes always exist even when they are not in use.  These
local maps are the values of the variables @code{lisp-mode-map},
@code{c-mode-map}, and so on.  Other modes are less frequently used, and
the local keymaps for these modes are constructed only when the mode is
used for the first time in a session.

  @xref{Standard Keymaps}, for a list of standard keymaps.

@defvar global-map
  This variable contains the default global keymap that maps Emacs
keyboard input to commands.  The value of @code{global-map} is a keymap
which is usually (but not necessarily) Emacs's global map.  The default
global keymap is a full keymap that binds @code{self-insert-command} to
all of the visible characters.

@end defvar

@defun current-global-map
@cindex global keymap
  This function returns the current global keymap.  Normally, this is
the same as the value of the @code{global-map}.

@example
(current-global-map)
@result{} [set-mark-command beginning-of-line @dots{} delete-backward-char]
@end example
@end defun

@defun current-local-map
@cindex local keymap
  This function returns the current buffer's local keymap, or
@code{nil} if it has none.  In the following example, the keymap for
the @code{*scratch*} buffer (using Lisp Interaction mode) is a sparse
keymap in which the entry for @key{ESC}, 27, is another sparse keymap.

@example
(current-local-map)
@result{} (keymap 
    (10 . eval-print-last-sexp) 
    (9 . lisp-indent-line) 
    (127 . backward-delete-char-untabify) 
    (27 keymap 
        (24 . eval-defun) 
        (17 . indent-sexp)))
@end example
@end defun

@defun use-global-map keymap
  This function makes @var{keymap} the new current global keymap.
The @var{keymap} map must be a full keymap (a vector of length 128).  It
returns @code{nil}.

  It is very unusual to change the global keymap (there are few
standard modes that do so).
@end defun

@defun use-local-map keymap
  This function makes @var{keymap} the new current local keymap of the
current buffer.  If @var{keymap} is @code{nil}, then there will be no
local keymap.  It returns @code{nil}.  Most major modes use this
function.
@end defun

@defun key-binding key
  This function returns the definition for @var{key} in the current
keymaps trying the current buffer's local map and then the global map.
The result is @code{nil} if @var{key} is undefined in the keymaps.

It is an error unless @var{key} is a string.

@example
(key-binding "\C-x\C-f")
    @result{} find-file
@end example
@end defun

@defun local-key-binding key
  This function returns the definition for @var{key} in the current
local keymap, or @code{nil}, if it is undefined there.
@end defun

@defun global-key-binding key
  This function returns the definition for command @var{key} in the
current global keymap, or @code{nil}, if it is undefined there.
@end defun

@defun accessible-keymaps keymap
  This function returns a list of all the keymaps that can be accessed,
via prefix keys, from @var{keymap}.  The list returned is an association
list with elements of the form @code{(@var{key} .@: @var{map})}, where
@var{key} is a prefix whose definition in @var{keymap} is @var{map}.

  The elements of the alist are ordered so that the @var{key} increases
in length.  The first element is always @code{("" .@: @var{keymap})},
which means that the empty string prefix gets you to the keymap you
start with.

  In the example below, the returned alist indicates that by typing
@key{ESC}, which is displayed as @code{"^["}, you will get to the sparse
keymap @code{(keymap (83 .@: center-paragraph) (115 .@: foo))}.

@example
(accessible-keymaps (current-local-map))
@result{}(("" keymap 
      (27 keymap   ; @r{Note this keymap for @key{ESC} appears below.}
          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))

   ("^[" keymap 
    (83 . center-paragraph) 
    (115 . foo)))
@end example

  In the following example, typing @kbd{C-h} will get you to the
sparse keymap starting @code{(118 . describe-variable) @dots{}}.
Typing @kbd{C-x 4}, will get you to the full keymap beginning
@code{[nil @dots{}]} (which happens to be @code{ctl-x-4-map}).

@example
(accessible-keymaps (current-global-map))
@result{} (("" . [set-mark-command beginning-of-line @dots{} 
              delete-backward-char])
    ("^C" keymap (13 . x-flush-mouse-queue))
    ("^H" keymap (118 . describe-variable) @dots{} (8 . help-for-help))
    ("^X" . [x-flush-mouse-queue  @dots{} backward-kill-sentence])
    ("^[" . [mark-sexp backward-sexp @dots{} backward-kill-word])
    ("^X4" . [nil @dots{} find-file-other-window nil @dots{} 
              nil nil]))
@end example
@end defun

@defun where-is-internal command &optional keymap firstonly
  This function returns list of key sequences (of any length) that are
bound to @var{command} in @var{keymap} and the global keymap.
@var{command} can be any object; it is compared with all keymap entries
using @code{eq}.  If @var{keymap} is not supplied, then the global map
is used.

  If @var{firstonly} is non-@code{nil}, then it returns a string
representing the first key sequence found, rather than a list of all
possible key sequences.  

  This function is used by @code{where-is} (@pxref{Help, , Help, emacs,
The GNU Emacs User Manual}).

@example
(where-is-internal 'kill-word)
    @result{} ("^[d" "^[OC")               ; @r{Locally, @code{kill-word} is}
                                    ; @r{bound to a function key}
                                    ; @r{as well as to @kbd{M-d}.}
@end example
@end defun

@deffn Command describe-bindings
  This function creates a listing of all defined keys, and their
definitions.  The listing is put in a buffer named @samp{*Help*}, which
then is displayed in a window.

@cindex control characters
@kindex meta characters
@kindex ESC
  A command using the @key{META} key is shown as @key{ESC} followed by the rest
of the key sequence.  A command using the control key is shown as @kbd{C-}
followed by the rest of the key sequence.

  A number of keys that all share the same definition are shown as the
first character followed by two dots, followed by the last character.
It does help to know @sc{ASCII} codes for this instance.  In the default
global map, @code{@key{SPC} ..@: ~} are all bound to
@code{self-insert-command}.  @key{SPC} is @sc{ASCII} 32, @kbd{~} is
@sc{ASCII} 126, and all the normal printing characters, (e.g., letters,
digits, punctuation, etc.@:) lie between these two.
@end deffn

@node Changing Key Bindings,  , Global and Local Keymaps, Keymaps
@section Changing Key Bindings

@cindex changing key bindings
@cindex rebinding
  The way to rebind a key is to change its binding in a keymap.  You can
change the global keymap, in which case the change is effective in all
buffers (except those that have their own overriding local definitions
for the same key).  Or you can change the current buffer's local map,
which usually affects the local keymap for all buffers using the same
major mode.  In addition, you can change bindings in any map that you
can access.

The @code{global-set-key} and @code{local-set-key} functions are
easiest to use.  People often use @code{global-set-key} in their
@file{.emacs} file for simple customization.

@table @kbd
@item @code{(global-set-key @var{key} @var{cmd})}
Defines @var{key} globally to run @var{cmd}.

@item @code{(local-set-key @var{key} @var{cmd})}
Defines @var{key} locally (in the major mode now in effect) to run
@var{cmd}.
@end table

  For example,

@example
(global-set-key "\C-x\C-\\" 'next-line)
@end example

@noindent
redefines @kbd{C-x C-\} to move down a line.

@cindex meta character keys
@cindex control character keys
@kindex ESC
  A special read syntax is provided to represent control and meta
characters (@pxref{String Type}).  In a string, the syntax @kbd{\C-}
means that the following character is a control character and @kbd{\M-}
means that the following character is a @key{META} character.  Thus, the
string @code{"\M-x"} is read as @kbd{M-x}, @code{"\C-f"} is read as
@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
@kbd{C-M-x}.

@pindex .emacs key bindings
  However, the most general way to modify a keymap is to use the
@code{define-key} function.  @code{define-key} takes three arguments:
the keymap, the key to modify in it, and the new definition.
(@code{global-set-key} is equivalent to @code{define-key} with
@code{current-global-map} as its first argument.)

  For the functions below, it is an error if an argument named @var{keymap}
is not a keymap or if an argument named @var{key} is not a string
representing characters to be typed.

@defun define-key keymap key definition
  This function adds a binding for @var{key} in @var{keymap}.  If
@var{key} is more than one character long, the change is actually made
in another keymap reached from @var{keymap}.  The @var{definition} can
be any Lisp object, but only certain types are meaningful.  (To see a
list of these objects, @pxref{Key Lookup}.)  The value returned by
@code{define-key} is @var{definition}.

@cindex invalid prefix characters error
@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 signalled (with data
@code{(error "Key sequence @var{key} uses invalid prefix characters")}).
If some prefix of @var{key} is undefined, then @var{define-key}
automatically defines it as a prefix key so that the rest of @var{key}
may be defined as specified.

  In the following example, a sparse keymap is created and a number of
bindings are added to it. 

@example
(setq map (make-sparse-keymap))
    @result{} (keymap)
(define-key map "\C-f" 'forward-char)
    @result{} forward-char
map
    @result{} (keymap (6 . forward-char))

;; @r{Build sparse map for @kbd{C-x} and bind @kbd{f} in that.}
(define-key map "\C-xf" 'forward-word)
    @result{} forward-word
map
@result{} (keymap 
    (24 keymap                ; @kbd{C-x}
        (102 . forward-word)) ;      @kbd{f}
    (6 . forward-char))       ; @kbd{C-f}

;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
(define-key map "\C-p" ctl-x-map)
@result{} [nil @dots{}  find-file @dots{} backward-kill-sentence] ; @code{ctl-x-map}

;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
(define-key map "\C-p\C-f" 'foo)
@result{} 'foo
map
@result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
    (16 . [nil @dots{}  foo @dots{} backward-kill-sentence])
    (24 keymap 
        (102 . forward-word))
    (6 . forward-char))
@end example

@noindent
In this example, @kbd{C-x C-f} has been changed in the default global
map as a result of this change in @code{ctl-x-map}.

  Note also that typing @kbd{C-p C-f} will execute the function @code{foo}
as will @kbd{C-x C-f}, since @code{ctl-x-map} was changed.
@end defun

@deffn Command global-set-key key definition
  This function gives @var{key} a definition of @var{definition} in the
global keymap.

@example
(global-set-key @var{key} @var{definition})
@equiv{}
(define-key (current-global-map) @var{key} @var{definition})
@end example
@end deffn

@deffn Command global-unset-key key
@cindex unbinding keys
  This function removes the definition of @var{key} from the current
global map.  One use of this function is to unset a key so that
a longer key may use the first key as a prefix---which would
not be allowed otherwise.  

@example
(global-unset-key @var{key})
@equiv{}
(define-key (current-global-map) @var{key} nil)
@end example

For example:

@example
(global-unset-key "\C-l")
    @result{} nil
(global-set-key "\C-l\C-l" 'redraw-display)
    @result{} nil
@end example
@end deffn

@deffn Command local-set-key key definition
  This function gives @var{key} a definition of @var{definition} in the
local keymap.

@example
(local-set-key @var{key} @var{definition})
@equiv{}
(define-key (current-local-map) @var{key} @var{definition})
@end example
@end deffn

@deffn Command local-unset-key key
  This function removes the definition of @var{key} from the current
local  map.

@example
(local-unset-key @var{key})
@equiv{}
(define-key (current-local-map) @var{key} nil)
@end example
@end deffn

@defun substitute-key-definition olddef newdef keymap
@cindex replace bindings
  This function replaces @var{olddef} with @var{newdef} for any keys in
@var{keymap} that were bound to @var{olddef}.  In other words, @var{olddef}
is replaced with @var{newdef} wherever it appears.

  It returns @code{nil}.

  Prefix keymaps that appear within @var{keymap} are not checked recursively
for keys bound to @var{olddef}; they are not changed at all.  Perhaps they
ought to be checked recursively.

@example
(setq map '(keymap 
	    (?1 . olddef-1) 
	    (?2 . olddef-2) 
	    (?3 . olddef-1)))
@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

(substitute-key-definition 'olddef-1 'newdef map)
@result{} nil
map
@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))

;; @r{The following will redefine @kbd{C-x C-f}, if you do it in an}
;; @r{Emacs with standard bindings.}

(substitute-key-definition 
 'find-file 'find-file-read-only (current-global-map))
@end example
@end defun

@defun suppress-keymap keymap &optional nodigits
@cindex @code{self-insert-command} override
  This function changes the contents of the full keymap @var{keymap} by
replacing the self insertion commands for numbers with the
@code{digit-argument} function, unless @var{nodigits} is non-@code{nil},
and by replacing the functions for the rest of the printing characters
with @code{undefined}.  This means that you are unable to type text
into a buffer after calling @code{suppress-keymap}.

  The function returns @code{nil}.

  Since this function does change @var{keymap}, you probably wish to use it
either with a new keymap or with a copy of a keymap, and use the
modified map locally.  Suppressing @code{global-map} would make it
impossible to use most of Emacs.

In @file{emacs/lisp/dired.el}, for example, a keymap is made for Dired
mode.  The beginning of the @code{define-key} sequence looks like this:

@example
  @dots{}
  (setq dired-mode-map (make-keymap))
  (suppress-keymap dired-mode-map)
  (define-key dired-mode-map "r" 'dired-rename-file)
  (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
  (define-key dired-mode-map "d" 'dired-flag-file-deleted)
  (define-key dired-mode-map "v" 'dired-view-file)
  (define-key dired-mode-map "e" 'dired-find-file)
  (define-key dired-mode-map "f" 'dired-find-file)
  @dots{}
@end example

@cindex yank suppression 
@cindex @code{quote-insert} suppression 
The @code{suppress-keymap} function does not make it impossible to
modify a buffer, as it does not suppress commands such as @code{yank}
and @code{quote-insert}.  (To prevent any modification of a buffer, make
it read-only.  (@xref{Read Only Buffers}.)

  The @code{suppress-keymap} function changes a keymap by replacing
the self insertion commands for numbers with the @code{digit-argument}
function and by replacing the functions for the rest of the printing
characters with @code{undefined}.

  In the following illustration, the first three lines containing
@code{self-insert-command} represent the ten digits.  The following line
represents all of the other printing characters.  The
@code{suppress-keymap} function replaces the @code{self-insert-command}
function with @code{digit-argument} and @code{undefined}.

@example
(setq map (copy-keymap (current-global-map)))
@result{} [set-mark-command ...         ; @r{@kbd{C-a}}
    self-insert-command ...             ; @r{@key{SPC}}
    self-insert-command                 ; @r{0}
    self-insert-command                 ; @r{1}
    self-insert-command ...             ; @r{2}
    self-insert-command ...             ; @r{other printing characters}
    delete-backward-char]               ; @r{@key{DEL}}

(suppress-keymap map)
@result{} nil

map
@result{} [set-mark-command ...         ; @r{@kbd{C-a}}
    undefined ...                       ; @r{@key{SPC}}
    digit-argument                      ; @r{0}                        
    digit-argument                      ; @r{1}                        
    digit-argument ...                  ; @r{2}                        
    undefined                           ; @r{what were} 
    undefined ...                       ; @r{other printing characters}
    delete-backward-char]               ; @r{@key{DEL}}
@end example
@end defun
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦344581cd6⟧ TextFile

Derivation

TextFile
