/[emacs]/emacs/lispref/keymaps.texi
ViewVC logotype

Diff of /emacs/lispref/keymaps.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.52 by rms, Thu Jun 24 20:16:02 2004 UTC revision 1.53 by teirllm, Tue Aug 10 15:40:14 2004 UTC
# Line 1  Line 1 
1  @c -*-texinfo-*-  @c -*-texinfo-*-
2  @c This is part of the GNU Emacs Lisp Reference Manual.  @c This is part of the GNU Emacs Lisp Reference Manual.
3  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004
4  @c   Free Software Foundation, Inc.  @c   Free Software Foundation, Inc.
5  @c See the file elisp.texi for copying conditions.  @c See the file elisp.texi for copying conditions.
6  @setfilename ../info/keymaps  @setfilename ../info/keymaps
# Line 103  representation; it is also convenient to Line 103  representation; it is also convenient to
103  This macro converts the text @var{keyseq-text} (a string constant)  This macro converts the text @var{keyseq-text} (a string constant)
104  into a key sequence (a string or vector constant).  The contents  into a key sequence (a string or vector constant).  The contents
105  of @var{keyseq-text} should describe the key sequence using the syntax  of @var{keyseq-text} should describe the key sequence using the syntax
106  used in this manual:  used in this manual.  More precisely, it uses the same syntax that
107    Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard
108    Macro,,, emacs, The GNU Emacs Manual}).
109    
110  @example  @example
111  (kbd "C-x") @result{} "\C-x"  (kbd "C-x") @result{} "\C-x"
112  (kbd "C-x C-f") @result{} "\C-x\C-f"  (kbd "C-x C-f") @result{} "\C-x\C-f"
 (kbd "C-c C-c") @result{} "\C-c\C-c"  
113  (kbd "C-x 4 C-f") @result{} "\C-x4\C-f"  (kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
114  (kbd "X") @result{} "X"  (kbd "X") @result{} "X"
115  (kbd "RET") @result{} "\^M"  (kbd "RET") @result{} "\^M"
116  (kbd "C-c 3") @result{} "\C-c3"  (kbd "C-c SPC") @result{} "\C-c@ "
117    (kbd "<f1> SPC") @result{} [f1 32]
118    (kbd "C-M-<down>") @result{} [C-M-down]
119  @end example  @end example
120  @end defmac  @end defmac
121    
# Line 144  This specifies a @dfn{default key bindin Line 147  This specifies a @dfn{default key bindin
147  elements of the keymap is given @var{binding} as its binding.  Default  elements of the keymap is given @var{binding} as its binding.  Default
148  bindings allow a keymap to bind all possible event types without having  bindings allow a keymap to bind all possible event types without having
149  to enumerate all of them.  A keymap that has a default binding  to enumerate all of them.  A keymap that has a default binding
150  completely masks any lower-precedence keymap.  completely masks any lower-precedence keymap, except for events
151    explicitly bound to @code{nil} (see below).
152    
153  @item @var{char-table}  @item @var{char-table}
154  If an element of a keymap is a char-table, it counts as holding  If an element of a keymap is a char-table, it counts as holding
# Line 251  satisfies @code{keymapp}. Line 255  satisfies @code{keymapp}.
255  @c ??? This should come after make-sparse-keymap  @c ??? This should come after make-sparse-keymap
256  @defun make-keymap &optional prompt  @defun make-keymap &optional prompt
257  This function creates and returns a new full keymap.  That keymap  This function creates and returns a new full keymap.  That keymap
258  contains a char-table (@pxref{Char-Tables}) with 384 slots: the first  contains a char-table (@pxref{Char-Tables}) with slots for all
259  128 slots are for defining all the @acronym{ASCII} characters, the next 128  characters without modifiers.  The new keymap initially binds all
260  slots are for 8-bit European characters, and each one of the final 128  these characters to @code{nil}, and does not bind any other kind of
261  slots is for one character set of non-@acronym{ASCII} characters supported by  event.
 Emacs.  The new keymap initially binds all these characters to  
 @code{nil}, and does not bind any other kind of event.  
262    
263  @example  @example
264  @group  @group
265  (make-keymap)  (make-keymap)
266      @result{} (keymap [nil nil nil @dots{} nil nil])      @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
267  @end group  @end group
268  @end example  @end example
269    
# Line 509  active keymap. Line 511  active keymap.
511    
512  @defun define-prefix-command symbol &optional mapvar prompt  @defun define-prefix-command symbol &optional mapvar prompt
513  @cindex prefix command  @cindex prefix command
514    @anchor{Definition of define-prefix-command}
515  This function prepares @var{symbol} for use as a prefix key's binding:  This function prepares @var{symbol} for use as a prefix key's binding:
516  it creates a sparse keymap and stores it as @var{symbol}'s function  it creates a sparse keymap and stores it as @var{symbol}'s function
517  definition.  Subsequently binding a key sequence to @var{symbol} will  definition.  Subsequently binding a key sequence to @var{symbol} will
# Line 698  all buffers. Line 701  all buffers.
701    
702  @defvar overriding-local-map  @defvar overriding-local-map
703  If non-@code{nil}, this variable holds a keymap to use instead of the  If non-@code{nil}, this variable holds a keymap to use instead of the
704  buffer's local keymap and instead of all the minor mode keymaps.  This  buffer's local keymap, text property or overlay keymaps, and instead
705  keymap, if any, overrides all other maps that would have been active,  of all the minor mode keymaps.  This keymap, if any, overrides all
706  except for the current global map.  other maps that would have been active, except for the current global
707    map.
708  @end defvar  @end defvar
709    
710  @defvar overriding-terminal-local-map  @defvar overriding-terminal-local-map
711  If non-@code{nil}, this variable holds a keymap to use instead of  If non-@code{nil}, this variable holds a keymap to use instead of
712  @code{overriding-local-map}, the buffer's local keymap and all the minor  @code{overriding-local-map}, the buffer's local keymap, text property
713  mode keymaps.  or overlay keymaps, and all the minor mode keymaps.
714    
715  This variable is always local to the current terminal and cannot be  This variable is always local to the current terminal and cannot be
716  buffer-local.  @xref{Multiple Displays}.  It is used to implement  buffer-local.  @xref{Multiple Displays}.  It is used to implement
# Line 977  An error is signaled if @var{key} is not Line 981  An error is signaled if @var{key} is not
981  @end example  @end example
982  @end defun  @end defun
983    
984  @defun current-active-maps  @defun current-active-maps &optional olp
985  This returns the list of keymaps that would be used by the command  This returns the list of keymaps that would be used by the command
986  loop in the current circumstances to look up a key sequence.  loop in the current circumstances to look up a key sequence.  Normally
987    it ignores @code{overriding-local-map} and
988    @code{overriding-terminal-local-map}, but if @var{olp} is
989    non-@code{nil} then it pays attention to them.
990  @end defun  @end defun
991    
992  @defun local-key-binding key &optional accept-defaults  @defun local-key-binding key &optional accept-defaults
# Line 1191  changing the bindings of both @kbd{C-p C Line 1198  changing the bindings of both @kbd{C-p C
1198  default global map.  default global map.
1199    
1200    The function @code{substitute-key-definition} scans a keymap for    The function @code{substitute-key-definition} scans a keymap for
1201  keys that have a certain binding and rebind them with a different  keys that have a certain binding and rebinds them with a different
1202  binding.  Another feature you can use for similar effects, but which  binding.  Another feature you can use for similar effects, but which
1203  is often cleaner, is to add a binding that remaps a command  is often cleaner, is to add a binding that remaps a command
1204  (@pxref{Remapping Commands}).  (@pxref{Remapping Commands}).
# Line 1324  this by making these two command-remappi Line 1331  this by making these two command-remappi
1331  Whenever @code{my-mode-map} is an active keymap, if the user types  Whenever @code{my-mode-map} is an active keymap, if the user types
1332  @kbd{C-k}, Emacs will find the standard global binding of  @kbd{C-k}, Emacs will find the standard global binding of
1333  @code{kill-line} (assuming nobody has changed it).  But  @code{kill-line} (assuming nobody has changed it).  But
1334  @code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map},  @code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
1335  so instead of running @code{kill-line}, Emacs runs  so instead of running @code{kill-line}, Emacs runs
1336  @code{my-kill-line}.  @code{my-kill-line}.
1337    
# Line 1337  Remapping only works through a single le Line 1344  Remapping only works through a single le
1344    
1345  @noindent  @noindent
1346  does not have the effect of remapping @code{kill-line} into  does not have the effect of remapping @code{kill-line} into
1347  @code{my-other-kill-line}.  If an ordinary key binding specifies  @code{my-other-kill-line}.  If an ordinary key binding specifies
1348  @code{kill-line}, this keymap will remap it to @code{my-kill-line};  @code{kill-line}, this keymap will remap it to @code{my-kill-line};
1349  if an ordinary binding specifies @code{my-kill-line}, this keymap will  if an ordinary binding specifies @code{my-kill-line}, this keymap will
1350  remap it to @code{my-other-kill-line}.  remap it to @code{my-other-kill-line}.
1351    
1352  @defun command-remapping command  @defun command-remapping command
1353  This function returns the remapping for @var{command}, given the  This function returns the remapping for @var{command} (a symbol),
1354  current active keymaps.  If @var{command} is not remapped (which is  given the current active keymaps.  If @var{command} is not remapped
1355  the usual situation), the function returns @code{nil}.  (which is the usual situation), or not a symbol, the function returns
1356    @code{nil}.
1357  @end defun  @end defun
1358    
1359  @node Key Binding Commands  @node Key Binding Commands
# Line 1409  actually bind the multibyte character wi Line 1417  actually bind the multibyte character wi
1417  Latin-1 character with code 246 (@kbd{M-v}).  In order to use this  Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
1418  binding, you need to enter the multibyte Latin-1 character as keyboard  binding, you need to enter the multibyte Latin-1 character as keyboard
1419  input.  One way to do this is by using an appropriate input method  input.  One way to do this is by using an appropriate input method
1420  (@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).  (@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
1421    
1422    If you want to use a unibyte character in the key binding, you can    If you want to use a unibyte character in the key binding, you can
1423  construct the key sequence string using @code{multibyte-char-to-unibyte}  construct the key sequence string using @code{multibyte-char-to-unibyte}
# Line 1499  association list with elements of the fo Line 1507  association list with elements of the fo
1507  @var{keymap} is @var{map}.  @var{keymap} is @var{map}.
1508    
1509  The elements of the alist are ordered so that the @var{key} increases  The elements of the alist are ordered so that the @var{key} increases
1510  in length.  The first element is always @code{("" .@: @var{keymap})},  in length.  The first element is always @code{([] .@: @var{keymap})},
1511  because the specified keymap is accessible from itself with a prefix of  because the specified keymap is accessible from itself with a prefix of
1512  no events.  no events.
1513    
# Line 1517  definition is the sparse keymap @code{(k Line 1525  definition is the sparse keymap @code{(k
1525  @smallexample  @smallexample
1526  @group  @group
1527  (accessible-keymaps (current-local-map))  (accessible-keymaps (current-local-map))
1528  @result{}(("" keymap  @result{}(([] keymap
1529        (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}        (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
1530            (83 . center-paragraph)            (83 . center-paragraph)
1531            (115 . center-line))            (115 . center-line))
# Line 1541  of a window. Line 1549  of a window.
1549  @smallexample  @smallexample
1550  @group  @group
1551  (accessible-keymaps (current-global-map))  (accessible-keymaps (current-global-map))
1552  @result{} (("" keymap [set-mark-command beginning-of-line @dots{}  @result{} (([] keymap [set-mark-command beginning-of-line @dots{}
1553                     delete-backward-char])                     delete-backward-char])
1554  @end group  @end group
1555  @group  @group
# Line 1572  The function @code{map-keymap} calls @va Line 1580  The function @code{map-keymap} calls @va
1580  for each binding in @var{keymap}.  It passes two arguments,  for each binding in @var{keymap}.  It passes two arguments,
1581  the event type and the value of the binding.  If @var{keymap}  the event type and the value of the binding.  If @var{keymap}
1582  has a parent, the parent's bindings are included as well.  has a parent, the parent's bindings are included as well.
1583    This works recursively: if the parent has itself a parent, then the
1584    grandparent's bindings are also included and so on.
1585    
1586  This function is the cleanest way to examine all the bindings  This function is the cleanest way to examine all the bindings
1587  in a keymap.  in a keymap.
# Line 1580  in a keymap. Line 1590  in a keymap.
1590  @defun where-is-internal command &optional keymap firstonly noindirect no-remap  @defun where-is-internal command &optional keymap firstonly noindirect no-remap
1591  This function is a subroutine used by the @code{where-is} command  This function is a subroutine used by the @code{where-is} command
1592  (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list  (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
1593  of key sequences (of any length) that are bound to @var{command} in a  of all key sequences (of any length) that are bound to @var{command} in a
1594  set of keymaps.  set of keymaps.
1595    
1596  The argument @var{command} can be any object; it is compared with all  The argument @var{command} can be any object; it is compared with all
# Line 1588  keymap entries using @code{eq}. Line 1598  keymap entries using @code{eq}.
1598    
1599  If @var{keymap} is @code{nil}, then the maps used are the current active  If @var{keymap} is @code{nil}, then the maps used are the current active
1600  keymaps, disregarding @code{overriding-local-map} (that is, pretending  keymaps, disregarding @code{overriding-local-map} (that is, pretending
1601  its value is @code{nil}).  If @var{keymap} is non-@code{nil}, then the  its value is @code{nil}).  If @var{keymap} is a keymap, then the
1602  maps searched are @var{keymap} and the global keymap.  If @var{keymap}  maps searched are @var{keymap} and the global keymap.  If @var{keymap}
1603  is a list of keymaps, only those keymaps are searched.  is a list of keymaps, only those keymaps are searched.
1604    
# Line 1598  keymaps that are active.  To search only Line 1608  keymaps that are active.  To search only
1608  @code{(keymap)} (an empty keymap) as @var{keymap}.  @code{(keymap)} (an empty keymap) as @var{keymap}.
1609    
1610  If @var{firstonly} is @code{non-ascii}, then the value is a single  If @var{firstonly} is @code{non-ascii}, then the value is a single
1611  string representing the first key sequence found, rather than a list of  vector representing the first key sequence found, rather than a list of
1612  all possible key sequences.  If @var{firstonly} is @code{t}, then the  all possible key sequences.  If @var{firstonly} is @code{t}, then the
1613  value is the first key sequence, except that key sequences consisting  value is the first key sequence, except that key sequences consisting
1614  entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}  entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
1615  characters) are preferred to all other key sequences.  characters) are preferred to all other key sequences and that the
1616    return value can never be a menu binding.
1617    
1618  If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't  If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1619  follow indirect keymap bindings.  This makes it possible to search for  follow indirect keymap bindings.  This makes it possible to search for
# Line 1623  other command.  However, if @var{no-rema Line 1634  other command.  However, if @var{no-rema
1634  @end smallexample  @end smallexample
1635  @end defun  @end defun
1636    
1637  @deffn Command describe-bindings &optional prefix  @deffn Command describe-bindings &optional prefix buffer-or-name
1638  This function creates a listing of all current key bindings, and  This function creates a listing of all current key bindings, and
1639  displays it in a buffer named @samp{*Help*}.  The text is grouped by  displays it in a buffer named @samp{*Help*}.  The text is grouped by
1640  modes---minor modes first, then the major mode, then global bindings.  modes---minor modes first, then the major mode, then global bindings.
# Line 1643  For example, in the default global map, Line 1654  For example, in the default global map,
1654  @kbd{~} is @acronym{ASCII} 126, and the characters between them include all  @kbd{~} is @acronym{ASCII} 126, and the characters between them include all
1655  the normal printing characters, (e.g., letters, digits, punctuation,  the normal printing characters, (e.g., letters, digits, punctuation,
1656  etc.@:); all these characters are bound to @code{self-insert-command}.  etc.@:); all these characters are bound to @code{self-insert-command}.
1657    
1658    If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
1659    buffer name.  Then @code{describe-bindings} lists that buffer's bindings,
1660    instead of the current buffer's.
1661  @end deffn  @end deffn
1662    
1663  @node Menu Keymaps  @node Menu Keymaps
# Line 1681  prompt string. Line 1696  prompt string.
1696    
1697  The easiest way to construct a keymap with a prompt string is to specify  The easiest way to construct a keymap with a prompt string is to specify
1698  the string as an argument when you call @code{make-keymap},  the string as an argument when you call @code{make-keymap},
1699  @code{make-sparse-keymap} or @code{define-prefix-command}  @code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
1700  (@pxref{Creating Keymaps}).  @code{define-prefix-command} (@pxref{Definition of define-prefix-command}).
1701    
1702    
1703  @defun keymap-prompt keymap  @defun keymap-prompt keymap
1704  This function returns the overall prompt string of @var{keymap},  This function returns the overall prompt string of @var{keymap},
# Line 2107  functioning of the menu itself, but they Line 2123  functioning of the menu itself, but they
2123  when the user selects from the menu, and they appear in the output of  when the user selects from the menu, and they appear in the output of
2124  @code{where-is} and @code{apropos}.  @code{where-is} and @code{apropos}.
2125    
2126      The menu in this example is intended for use with the mouse.  If a
2127    menu is intended for use with the keyboard, that is, if it is bound to
2128    a key sequence ending with a keyboard event, then the menu items
2129    should be bound to characters or ``real'' function keys, that can be
2130    typed with the keyboard.
2131    
2132    The binding whose definition is @code{("--")} is a separator line.    The binding whose definition is @code{("--")} is a separator line.
2133  Like a real menu item, the separator has a key symbol, in this case  Like a real menu item, the separator has a key symbol, in this case
2134  @code{separator-ps-print}.  If one menu has two separators, they must  @code{separator-ps-print}.  If one menu has two separators, they must
# Line 2389  property list elements to add to the men Line 2411  property list elements to add to the men
2411  This function is used for making non-global tool bar items.  Use it  This function is used for making non-global tool bar items.  Use it
2412  like @code{tool-bar-add-item-from-menu} except that @var{in-map}  like @code{tool-bar-add-item-from-menu} except that @var{in-map}
2413  specifies the local map to make the definition in.  The argument  specifies the local map to make the definition in.  The argument
2414  @var{from-map} si like the @var{map} argument of  @var{from-map} is like the @var{map} argument of
2415  @code{tool-bar-add-item-from-menu}.  @code{tool-bar-add-item-from-menu}.
2416  @end defun  @end defun
2417    

Legend:
Removed from v.1.52  
changed lines
  Added in v.1.53

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26