/[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.39.4.1 by miles, Fri Apr 4 06:20:41 2003 UTC revision 1.39.4.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 28  found.  The whole process is called @dfn Line 28  found.  The whole process is called @dfn
28  * Key Lookup::                  How extracting elements from keymaps works.  * Key Lookup::                  How extracting elements from keymaps works.
29  * Functions for Key Lookup::    How to request key lookup.  * Functions for Key Lookup::    How to request key lookup.
30  * Changing Key Bindings::       Redefining a key in a keymap.  * Changing Key Bindings::       Redefining a key in a keymap.
31    * Remapping Commands::          Bindings that translate one command to another.
32  * Key Binding Commands::        Interactive interfaces for redefining keys.  * Key Binding Commands::        Interactive interfaces for redefining keys.
33  * Scanning Keymaps::            Looking through all keymaps, for printing help.  * Scanning Keymaps::            Looking through all keymaps, for printing help.
34  * Menu Keymaps::                Defining a menu as a keymap.  * Menu Keymaps::                Defining a menu as a keymap.
# Line 124  bindings allow a keymap to bind all poss Line 125  bindings allow a keymap to bind all poss
125  to enumerate all of them.  A keymap that has a default binding  to enumerate all of them.  A keymap that has a default binding
126  completely masks any lower-precedence keymap.  completely masks any lower-precedence keymap.
127    
128  @item @var{vector}  @item @var{char-table}
129  If an element of a keymap is a vector, the vector counts as bindings for  If an element of a keymap is a char-table, it counts as holding
130  all the @sc{ascii} characters, codes 0 through 127; vector element  bindings for all character events with no modifier bits
131  @var{n} is the binding for the character with code @var{n}.  This is a  (@pxref{modifier bits}): element @var{n} is the binding for the
132  compact way to record lots of bindings.  A keymap with such a vector is  character with code @var{n}.  This is a compact way to record lots of
133  called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse  bindings.  A keymap with such a char-table is called a @dfn{full
134  keymaps}.  keymap}.  Other keymaps are called @dfn{sparse keymaps}.
135    
136  A @code{nil} binding is used to mean that a key is explicitly not bound.  When a keymap contains a char-table vector, it always defines a
137  Just like any other binding, it takes precedence over a default binding  binding for each character without modifiers.  However, if the binding
138  or a binding in the parent keymap, but on the other hand, it does not  is @code{nil}, it doesn't constitute a definition.  @code{nil} takes
139  take precedence over keymaps of lower priority.  precedence over a default binding or a binding in the parent keymap.
140    So in a full keymap, default bindings are not meaningful for
141  When a keymap contains a vector, it always defines a binding for each  characters without modifiers.  They can still apply to characters with
142  @sc{ascii} character, even if the vector contains @code{nil} for that  modifier bits and to non-character events.  A binding of @code{nil}
143  character.  Such a binding of @code{nil} overrides any default key  does @emph{not} override lower-precedence keymaps; thus, if the local
144  binding in the keymap, for @sc{ascii} characters.  However, default  map gives a binding of @code{nil}, Emacs uses the binding from the
145  bindings are still meaningful for events other than @sc{ascii}  global map.
 characters.  A binding of @code{nil} does @emph{not} override  
 lower-precedence keymaps; thus, if the local map gives a binding of  
 @code{nil}, Emacs uses the binding from the global map.  
146    
147  @item @var{string}  @item @var{string}
148  @cindex keymap prompt string  @cindex keymap prompt string
# Line 530  when the minor mode is enabled. Line 528  when the minor mode is enabled.
528    
529    The variable @code{overriding-local-map}, if non-@code{nil}, specifies    The variable @code{overriding-local-map}, if non-@code{nil}, specifies
530  another local keymap that overrides the buffer's local map and all the  another local keymap that overrides the buffer's local map and all the
531  minor mode keymaps.  minor mode keymaps.  Modes for emulation can specify additional
532    active keymaps through the variable @code{emulation-mode-map-alists}.
533    
534    All the active keymaps are used together to determine what command to    All the active keymaps are used together to determine what command to
535  execute when a key is entered.  Emacs searches these maps one by one, in  execute when a key is entered.  Emacs searches these maps one by one, in
# Line 714  binding in this keymap, then it is speci Line 713  binding in this keymap, then it is speci
713  event is run directly by @code{read-event}.  @xref{Special Events}.  event is run directly by @code{read-event}.  @xref{Special Events}.
714  @end defvar  @end defvar
715    
716    @defvar emulation-mode-map-alists
717    This variable holds a list of keymap alists to use for emulations
718    modes.  It is intended for modes or packages using multiple minor-mode
719    keymaps.  Each element is a keymap alist which has the same format and
720    meaning as @code{minor-mode-map-alist}, or a symbol with a variable
721    binding which is such an alist.  The ``active'' keymaps in each alist
722    are used before @code{minor-mode-map-alist} and
723    @code{minor-mode-overriding-map-alist}.
724    @end defvar
725    
726  @node Key Lookup  @node Key Lookup
727  @section Key Lookup  @section Key Lookup
728  @cindex key lookup  @cindex key lookup
# Line 918  Used in keymaps to undefine keys.  It ca Line 927  Used in keymaps to undefine keys.  It ca
927  not cause an error.  not cause an error.
928  @end deffn  @end deffn
929    
930  @defun key-binding key &optional accept-defaults  @defun key-binding key &optional accept-defaults no-remap
931  This function returns the binding for @var{key} in the current  This function returns the binding for @var{key} in the current
932  keymaps, trying all the active keymaps.  The result is @code{nil} if  keymaps, trying all the active keymaps.  The result is @code{nil} if
933  @var{key} is undefined in the keymaps.  @var{key} is undefined in the keymaps.
# Line 927  keymaps, trying all the active keymaps. Line 936  keymaps, trying all the active keymaps.
936  The argument @var{accept-defaults} controls checking for default  The argument @var{accept-defaults} controls checking for default
937  bindings, as in @code{lookup-key} (above).  bindings, as in @code{lookup-key} (above).
938    
939    When commands are remapped (@pxref{Remapping Commands}),
940    @code{key-binding} normally processes command remappings so as to
941    returns the remapped command that will actually be executed.  However,
942    if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
943    remappings and returns the binding directly specified for @var{key}.
944    
945  An error is signaled if @var{key} is not a string or a vector.  An error is signaled if @var{key} is not a string or a vector.
946    
947  @example  @example
# Line 937  An error is signaled if @var{key} is not Line 952  An error is signaled if @var{key} is not
952  @end example  @end example
953  @end defun  @end defun
954    
955    @defun current-active-maps
956    This returns the list of keymaps that would be used by the command
957    loop in the current circumstances to look up a key sequence.
958    @end defun
959    
960  @defun local-key-binding key &optional accept-defaults  @defun local-key-binding key &optional accept-defaults
961  This function returns the binding for @var{key} in the current  This function returns the binding for @var{key} in the current
962  local keymap, or @code{nil} if it is undefined there.  local keymap, or @code{nil} if it is undefined there.
# Line 1145  changing an entry in @code{ctl-x-map}, a Line 1165  changing an entry in @code{ctl-x-map}, a
1165  changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the  changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1166  default global map.  default global map.
1167    
1168      The function @code{substitute-key-definition} scans a keymap for
1169    keys that have a certain binding and rebind them with a different
1170    binding.  Another feature you can use for similar effects, but which
1171    is often cleaner, is to add a binding that remaps a command
1172    (@pxref{Remapping Commands}).
1173    
1174  @defun substitute-key-definition olddef newdef keymap &optional oldmap  @defun substitute-key-definition olddef newdef keymap &optional oldmap
1175  @cindex replace bindings  @cindex replace bindings
1176  This function replaces @var{olddef} with @var{newdef} for any keys in  This function replaces @var{olddef} with @var{newdef} for any keys in
# Line 1179  bindings in another.  For example, Line 1205  bindings in another.  For example,
1205  puts the special deletion command in @code{my-map} for whichever keys  puts the special deletion command in @code{my-map} for whichever keys
1206  are globally bound to the standard deletion command.  are globally bound to the standard deletion command.
1207    
 @ignore  
 @c Emacs 18 only  
 Prefix keymaps that appear within @var{keymap} are not checked  
 recursively for keys bound to @var{olddef}; they are not changed at all.  
 Perhaps it would be better to check nested keymaps recursively.  
 @end ignore  
   
1208  Here is an example showing a keymap before and after substitution:  Here is an example showing a keymap before and after substitution:
1209    
1210  @smallexample  @smallexample
# Line 1254  Dired mode is set up: Line 1273  Dired mode is set up:
1273  @end smallexample  @end smallexample
1274  @end defun  @end defun
1275    
1276    @node Remapping Commands
1277    @section Remapping Commands
1278    @cindex remapping commands
1279    
1280      A special kind of key binding, using a special ``key sequence''
1281    which includes a command name, has the effect of @dfn{remapping} that
1282    command into another.  Here's how it works.  You make a key binding
1283    for a key sequence that starts with the dummy event @code{remap},
1284    followed by the command name you want to remap.  Specify the remapped
1285    definition as the definition in this binding.  The remapped definition
1286    is usually a command name, but it can be any valid definition for
1287    a key binding.
1288    
1289      Here's an example.  Suppose that My mode uses special commands
1290    @code{my-kill-line} and @code{my-kill-word}, which should be invoked
1291    instead of @code{kill-line} and @code{kill-word}.  It can establish
1292    this by making these two command-remapping bindings in its keymap:
1293    
1294    @example
1295    (define-key my-mode-map [remap kill-line] 'my-kill-line)
1296    (define-key my-mode-map [remap kill-word] 'my-kill-word)
1297    @end example
1298    
1299    Whenever @code{my-mode-map} is an active keymap, if the user types
1300    @kbd{C-k}, Emacs will find the standard global binding of
1301    @code{kill-line} (assuming nobody has changed it).  But
1302    @code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map},
1303    so instead of running @code{kill-line}, Emacs runs
1304    @code{my-kill-line}.
1305    
1306    Remapping only works through a single level.  In other words,
1307    
1308    @example
1309    (define-key my-mode-map [remap kill-line] 'my-kill-line)
1310    (define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
1311    @end example
1312    
1313    @noindent
1314    does not have the effect of remapping @code{kill-line} into
1315    @code{my-other-kill-line}.  If an ordinary key binding specifies
1316    @code{kill-line}, this keymap will remap it to @code{my-kill-line};
1317    if an ordinary binding specifies @code{my-kill-line}, this keymap will
1318    remap it to @code{my-other-kill-line}.
1319    
1320    @defun command-remapping command
1321    This function returns the remapping for @var{command}, given the
1322    current active keymaps.  If @var{command} is not remapped (which is
1323    the usual situation), the function returns @code{nil}.
1324    @end defun
1325    
1326  @node Key Binding Commands  @node Key Binding Commands
1327  @section Commands for Binding Keys  @section Commands for Binding Keys
1328    
# Line 1473  of a window. Line 1542  of a window.
1542  These are not all the keymaps you would see in actuality.  These are not all the keymaps you would see in actuality.
1543  @end defun  @end defun
1544    
1545  @defun where-is-internal command &optional keymap firstonly noindirect  @defun map-keymap function keymap
1546    The function @code{map-keymap} calls @var{function} once
1547    for each binding in @var{keymap}.  It passes two arguments,
1548    the event type and the value of the binding.  If @var{keymap}
1549    has a parent, the parent's bindings are included as well.
1550    
1551    This function is the cleanest way to examine all the bindings
1552    in a keymap.
1553    @end defun
1554    
1555    @defun where-is-internal command &optional keymap firstonly noindirect no-remap
1556  This function is a subroutine used by the @code{where-is} command  This function is a subroutine used by the @code{where-is} command
1557  (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list  (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
1558  of key sequences (of any length) that are bound to @var{command} in a  of key sequences (of any length) that are bound to @var{command} in a
# Line 1504  If @var{noindirect} is non-@code{nil}, @ Line 1583  If @var{noindirect} is non-@code{nil}, @
1583  follow indirect keymap bindings.  This makes it possible to search for  follow indirect keymap bindings.  This makes it possible to search for
1584  an indirect definition itself.  an indirect definition itself.
1585    
1586    When command remapping is in effect (@pxref{Remapping Commands}),
1587    @code{where-is-internal} figures out when a command will be run due to
1588    remapping and reports keys accordingly.  It also returns @code{nil} if
1589    @var{command} won't really be run because it has been remapped to some
1590    other command.  However, if @var{no-remap} is non-@code{nil}.
1591    @code{where-is-internal} ignores remappings.
1592    
1593  @smallexample  @smallexample
1594  @group  @group
1595  (where-is-internal 'describe-function)  (where-is-internal 'describe-function)
# Line 1573  the string as an argument when you call Line 1659  the string as an argument when you call
1659  @code{make-sparse-keymap} or @code{define-prefix-command}  @code{make-sparse-keymap} or @code{define-prefix-command}
1660  (@pxref{Creating Keymaps}).  (@pxref{Creating Keymaps}).
1661    
1662    @defun keymap-prompt keymap
1663    This function returns the overall prompt string of @var{keymap},
1664    or @code{nil} if it has none.
1665    @end defun
1666    
1667  The order of items in the menu is the same as the order of bindings in  The order of items in the menu is the same as the order of bindings in
1668  the keymap.  Since @code{define-key} puts new bindings at the front, you  the keymap.  Since @code{define-key} puts new bindings at the front, you
1669  should define the menu items starting at the bottom of the menu and  should define the menu items starting at the bottom of the menu and
# Line 1603  looks like this: Line 1694  looks like this:
1694  @noindent  @noindent
1695  The @sc{car}, @var{item-string}, is the string to be displayed in the  The @sc{car}, @var{item-string}, is the string to be displayed in the
1696  menu.  It should be short---preferably one to three words.  It should  menu.  It should be short---preferably one to three words.  It should
1697  describe the action of the command it corresponds to.  describe the action of the command it corresponds to.  Note that it is
1698    not generally possible to display non-ASCII text in menus.  It will
1699    work for keyboard menus and will work to a large extent when Emacs is
1700    built with Gtk+ support.@footnote{In this case, the text is first
1701    encoded using the @code{utf-8} coding system and then rendered by the
1702    toolkit as it sees fit.}
1703    
1704  You can also supply a second string, called the help string, as follows:  You can also supply a second string, called the help string, as follows:
1705    
# Line 2250  To define items in some local map, bind Line 2346  To define items in some local map, bind
2346    
2347  @defun tool-bar-add-item-from-menu command icon &optional map &rest props  @defun tool-bar-add-item-from-menu command icon &optional map &rest props
2348  @tindex tool-bar-add-item-from-menu  @tindex tool-bar-add-item-from-menu
2349  This command is a convenience for defining tool bar items which are  This function is a convenience for defining tool bar items which are
2350  consistent with existing menu bar bindings.  The binding of  consistent with existing menu bar bindings.  The binding of
2351  @var{command} is looked up in the menu bar in @var{map} (default  @var{command} is looked up in the menu bar in @var{map} (default
2352  @code{global-map}) and modified to add an image specification for  @code{global-map}) and modified to add an image specification for
2353  @var{icon}, which is looked for in the same way as by  @var{icon}, which is found in the same way as by
2354  @code{tool-bar-add-item}.  The resulting binding is then placed in  @code{tool-bar-add-item}.  The resulting binding is then placed in
2355  @code{tool-bar-map}.  @var{map} must contain an appropriate keymap bound  @code{tool-bar-map}, so use this function only for global tool bar
2356  to @code{[menu-bar]}.  The remaining arguments @var{props} are  items.
2357  additional property list elements to add to the menu item specification.  
2358    @var{map} must contain an appropriate keymap bound to
2359    @code{[menu-bar]}.  The remaining arguments @var{props} are additional
2360    property list elements to add to the menu item specification.
2361    @end defun
2362    
2363    @defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
2364    This function is used for making non-global tool bar items.  Use it
2365    like @code{tool-bar-add-item-from-menu} except that @var{in-map}
2366    specifies the local map to make the definition in.  The argument
2367    @var{from-map} si like the @var{map} argument of
2368    @code{tool-bar-add-item-from-menu}.
2369  @end defun  @end defun
2370    
2371  @tindex auto-resize-tool-bar  @tindex auto-resize-tool-bar
# Line 2351  menu of Shell mode, after the item @code Line 2458  menu of Shell mode, after the item @code
2458    [work] '("Work" . work-command) 'break)    [work] '("Work" . work-command) 'break)
2459  @end example  @end example
2460  @end defun  @end defun
2461    
2462    @ignore
2463       arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
2464    @end ignore

Legend:
Removed from v.1.39.4.1  
changed lines
  Added in v.1.39.4.2

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