(hs-hide-block): Fix message spelling.

[bpt/emacs.git] / lispref / keymaps.texi

diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 02bada6..e8edf59 100644 (file)
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -74,7 +74,7 @@ intermediate bindings (found for the events before the last) are all
 keymaps; if this is not so, the sequence of events does not form a
 unit---it is not really a key sequence.  In other words, removing one or
 more events from the end of any valid key must always yield a prefix
 keymaps; if this is not so, the sequence of events does not form a
 unit---it is not really a key sequence.  In other words, removing one or
 more events from the end of any valid key must always yield a prefix

-key.  For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix
+key.  For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix

 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
 
   Note that the set of possible multi-event key sequences depends on the
 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
 
   Note that the set of possible multi-event key sequences depends on the


@@ -207,6 +207,7 @@ otherwise.  More precisely, this function tests for a list whose
 
   Here we describe the functions for creating keymaps.
 
 
   Here we describe the functions for creating keymaps.
 

+@c ??? This should come after makr-sparse-keymap

 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap (i.e., one
 containing a vector of length 128 for defining all the @sc{ASCII}
 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap (i.e., one
 containing a vector of length 128 for defining all the @sc{ASCII}


@@ -570,9 +571,8 @@ is the order of @code{minor-mode-map-alist}.  But you should design
 minor modes so that they don't interfere with each other.  If you do
 this properly, the order will not matter.
 
 minor modes so that they don't interfere with each other.  If you do
 this properly, the order will not matter.
 

-See also @code{minor-mode-key-binding} in @ref{Functions for Key
-Lookup}.  See @ref{Keymaps and Minor Modes}, for more information about
-minor modes.
+See also @code{minor-mode-key-binding}, above.  See @ref{Keymaps and
+Minor Modes}, for more information about minor modes.

 @end defvar
 
 @defvar overriding-local-map
 @end defvar
 
 @defvar overriding-local-map


@@ -582,6 +582,31 @@ keymap, if any, overrides all other maps that would have been active,
 except for the current global map.
 @end defvar
 
 except for the current global map.
 @end defvar
 

+@defvar overriding-terminal-local-map
+If non-@code{nil}, this variable holds a keymap to use instead of
+@code{overriding-local-map}, the buffer's local keymap and all the minor
+mode keymaps.
+
+This variable is always local to the current terminal and cannot be
+buffer-local.  @xref{Multiple Displays}.  It is used to implement
+incremental search mode.
+@end defvar
+
+@defvar overriding-local-map-menu-flag
+If this variable is non-@code{nil}, the value of
+@code{overriding-local-map} or @code{overriding-terminal-local-map} can
+affect the display of the menu bar.  The default value is @code{nil}, so
+those map variables have no effect on the menu bar.
+
+Note that these two map variables do affect the execution of key
+sequences entered using the menu bar, even if they do not affect the
+menu bar display.  So if a menu bar key sequence comes in, you should
+clear the variables before looking up and executing that key sequence.
+Modes that use the variables would typically do this anyway; normally
+they respond to events that they do not handle by ``unreading'' them and
+exiting.
+@end defvar
+

 @node Key Lookup
 @section Key Lookup
 @cindex key lookup
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup


@@ -635,12 +660,11 @@ event of the key sequence is looked up in @var{keymap}.
 The events used so far in the lookup form a complete key,
 and @var{command} is its binding.  @xref{What Is a Function}.
 
 The events used so far in the lookup form a complete key,
 and @var{command} is its binding.  @xref{What Is a Function}.
 

-@item @var{string}
-@itemx @var{vector}
+@item @var{array}

 @cindex string in keymap
 @cindex string in keymap

-The events used so far in the lookup form a complete key, whose
-binding is a keyboard macro.  See @ref{Keyboard Macros}, for more
-information.
+The array (either a string or a vector) is a keyboard macro.  The events
+used so far in the lookup form a complete key, and the array is its
+binding.  See @ref{Keyboard Macros}, for more information.

 
 @item @var{list}
 @cindex list in keymap
 
 @item @var{list}
 @cindex list in keymap


@@ -670,7 +694,7 @@ binding of @var{othertype} in @var{othermap} and uses that.
 
 This feature permits you to define one key as an alias for another key.
 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
 
 This feature permits you to define one key as an alias for another key.
 For example, an entry whose @sc{car} is the keymap called @code{esc-map}

-and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
+and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global

 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
 @end itemize
 
 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
 @end itemize
 


@@ -913,6 +937,17 @@ containing a single @kbd{C-M-x}.  You can also use this escape syntax in
 vectors, as well as others that aren't allowed in strings; one example
 is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
 
 vectors, as well as others that aren't allowed in strings; one example
 is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
 

+  The key definition and lookup functions accept an alternate syntax for
+event types in a key sequence that is a vector: you can use a list
+containing modifier names plus one base event (a character or function
+key name).  For example, @code{(control ?a)} is equivalent to
+@code{?\C-a} and @code{(hyper control left)} is equivalent to
+@code{C-H-left}.
+
+  One advantage of using a list to represent the event type is that the
+precise numeric codes for the modifier bits don't appear in compiled
+files.
+

   For the functions below, an error is signaled if @var{keymap} is not a
 keymap or if @var{key} is not a string or vector representing a key
 sequence.  You can use event types (symbols) as shorthand for events
   For the functions below, an error is signaled if @var{keymap} is not a
 keymap or if @var{key} is not a string or vector representing a key
 sequence.  You can use event types (symbols) as shorthand for events


@@ -1123,6 +1158,13 @@ or
 (global-set-key [?\C-x ?\C-\\] 'next-line)
 @end smallexample
 
 (global-set-key [?\C-x ?\C-\\] 'next-line)
 @end smallexample
 

+@noindent
+or
+
+@smallexample
+(global-set-key [(control ?x) (control ?\\)] 'next-line)
+@end smallexample
+

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


@@ -1378,6 +1420,13 @@ the menu.  The easiest way to construct a keymap with a prompt string is
 to specify the string as an argument when you call @code{make-keymap} or
 @code{make-sparse-keymap} (@pxref{Creating Keymaps}).
 
 to specify the string as an argument when you call @code{make-keymap} or
 @code{make-sparse-keymap} (@pxref{Creating Keymaps}).
 

+The order of items in the menu is the same as the order of bindings in
+the keymap.  Since @code{define-key} puts new bindings at the front, you
+should define the menu items starting at the bottom of the menu and
+moving to the top, if you care about the order.  When you add an item to
+an existing menu, you can specify its position in the menu using
+@code{define-key-after} (@pxref{Modifying Menus}).
+

 The individual bindings in the menu keymap should have item
 strings; these strings become the items displayed in the menu.  A
 binding with an item string looks like this:
 The individual bindings in the menu keymap should have item
 strings; these strings become the items displayed in the menu.  A
 binding with an item string looks like this:


@@ -1402,8 +1451,8 @@ You can also supply a second string, called the help string, as follows:
 
 Currently Emacs does not actually use @var{help-string}; it knows only
 how to ignore @var{help-string} in order to extract @var{real-binding}.
 
 Currently Emacs does not actually use @var{help-string}; it knows only
 how to ignore @var{help-string} in order to extract @var{real-binding}.

-In the future we hope to make @var{help-string} serve as extended
-documentation for the menu item, available on request.
+In the future we may use @var{help-string} as extended documentation for
+the menu item, available on request.

 
 If @var{real-binding} is @code{nil}, then @var{string} appears in the
 menu but cannot be selected.
 
 If @var{real-binding} is @code{nil}, then @var{string} appears in the
 menu but cannot be selected.


@@ -1416,12 +1465,22 @@ the menu item only if the expression's value is non-@code{nil}.  When a
 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
 cannot be selected with the mouse.
 
 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
 cannot be selected with the mouse.
 

-The order of items in the menu is the same as the order of bindings in
-the keymap.  Since @code{define-key} puts new bindings at the front, you
-should define the menu items starting at the bottom of the menu and
-moving to the top, if you care about the order.  When you add an item to
-an existing menu, you can specify its position in the menu using
-@code{define-key-after} (@pxref{Modifying Menus}).
+The menu bar does not recalculate which items are enabled every time you
+look at a menu.  This is because the X toolkit requires the whole tree
+of menus in advance.  To force recalculation of the menu bar, call
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
+Sometimes it is useful to make menu items that use the ``same'' command
+but with different enable conditions.  You can do this by defining alias
+commands.  Here's an example that makes two aliases for
+@code{toggle-read-only} and gives them different enable conditions:
+
+@example
+(defalias 'make-read-only 'toggle-read-only)
+(put 'make-read-only 'menu-enable '(not buffer-read-only))
+(defalias 'make-writable 'toggle-read-only)
+(put 'make-writable 'menu-enable 'buffer-read-only)
+@end example

 
 You've probably noticed that menu items show the equivalent keyboard key
 sequence (if any) to invoke the same command.  To save time on
 
 You've probably noticed that menu items show the equivalent keyboard key
 sequence (if any) to invoke the same command.  To save time on


@@ -1437,6 +1496,11 @@ Don't put these sublists in the menu item yourself; menu display
 calculates them automatically.  Don't add keyboard equivalents to the
 item strings in a mouse menu, since that is redundant.
 
 calculates them automatically.  Don't add keyboard equivalents to the
 item strings in a mouse menu, since that is redundant.
 

+If an alias command has no keyboard equivalent itself, menus show the
+keyboard equivalent of its underlying command.  In the example above,
+menu items defined to run @code{make-read-only} or @code{make-writable}
+would show the keyboard equivalents of @code{toggle-read-only}.
+

 @node Mouse Menus
 @subsection Menus and the Mouse
 
 @node Mouse Menus
 @subsection Menus and the Mouse
 


@@ -1500,10 +1564,14 @@ When the user has found the desired alternative from the menu, he or she
 should type the corresponding character---the one whose binding is that
 alternative.
 
 should type the corresponding character---the one whose binding is that
 alternative.
 

+@ignore

 In a menu intended for keyboard use, each menu item must clearly
 indicate what character to type.  The best convention to use is to make
 In a menu intended for keyboard use, each menu item must clearly
 indicate what character to type.  The best convention to use is to make

-the character the first letter of the item string.  That is something
-users will understand without being told.
+the character the first letter of the item string---that is something
+users will understand without being told.  We plan to change this; by
+the time you read this manual, keyboard menus may explicitly name the
+key for each alternative.
+@end ignore

 
 This way of using menus in an Emacs-like editor was inspired by the
 Hierarkey system.
 
 This way of using menus in an Emacs-like editor was inspired by the
 Hierarkey system.


@@ -1568,12 +1636,17 @@ that menu bar item, it brings up a single, combined submenu containing
 all the subcommands of that item---the global subcommands, the local
 subcommands, and the minor mode subcommands, all together.
 
 all the subcommands of that item---the global subcommands, the local
 subcommands, and the minor mode subcommands, all together.
 

+  The variable @code{overriding-local-map} is normally ignored when
+determining the menu bar contents.  That is, the menu bar is computed
+from the keymaps that would be active if @code{overriding-local-map}
+were @code{nil}.  @xref{Active Keymaps}.
+

   In order for a frame to display a menu bar, its @code{menu-bar-lines}
 parameter must be greater than zero.  Emacs uses just one line for the
 menu bar itself; if you specify more than one line, the other lines
 serve to separate the menu bar from the windows in the frame.  We
   In order for a frame to display a menu bar, its @code{menu-bar-lines}
 parameter must be greater than zero.  Emacs uses just one line for the
 menu bar itself; if you specify more than one line, the other lines
 serve to separate the menu bar from the windows in the frame.  We

-recommend you try 1 or 2 as the value of @code{menu-bar-lines}.  @xref{X
-Frame Parameters}.
+recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{X Frame
+Parameters}.

 
   Here's an example of setting up a menu bar item:
 
 
   Here's an example of setting up a menu bar item:
 


@@ -1638,7 +1711,10 @@ the menu.  To put it elsewhere, use @code{define-key-after}:
 @defun define-key-after map key binding after
 Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after
 @defun define-key-after map key binding after
 Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after

-the binding for the event @var{after}.  For example,
+the binding for the event @var{after}.  The argument @var{key} should
+be of length one---a vector or string with just one element.
+
+For example,

 
 @example
 (define-key-after my-menu [drink]
 
 @example
 (define-key-after my-menu [drink]