+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps
-
-Key Lookup
-==========
-
- "Key lookup" is the process of finding the binding of a key sequence
-from a given keymap. Actual execution of the binding is not part of
-key lookup.
-
- Key lookup uses just the event type of each event in the key
-sequence; the rest of the event is ignored. In fact, a key sequence
-used for key lookup may designate mouse events with just their types
-(symbols) instead of with entire mouse events (lists). *Note Events::.
-Such a pseudo-key-sequence is insufficient for `command-execute', but
-it is sufficient for looking up or rebinding a key.
-
- When the key sequence consists of multiple events, key lookup
-processes the events sequentially: the binding of the first event is
-found, and must be a keymap; then the second event's binding is found in
-that keymap, and so on until all the events in the key sequence are used
-up. (The binding thus found for the last event may or may not be a
-keymap.) Thus, the process of key lookup is defined in terms of a
-simpler process for looking up a single event in a keymap. How that is
-done depends on the type of object associated with the event in that
-keymap.
-
- Let's use the term "keymap entry" to describe the value found by
-looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in menu key bindings because
-`lookup-key' and other key lookup functions don't include them in the
-returned value.) While any Lisp object may be stored in a keymap as a
-keymap entry, not all make sense for key lookup. Here is a list of the
-meaningful kinds of keymap entries:
-
-`nil'
- `nil' means that the events used so far in the lookup form an
- undefined key. When a keymap fails to mention an event type at
- all, and has no default binding, that is equivalent to a binding
- of `nil' for that event type.
-
-KEYMAP
- The events used so far in the lookup form a prefix key. The next
- event of the key sequence is looked up in KEYMAP.
-
-COMMAND
- The events used so far in the lookup form a complete key, and
- COMMAND is its binding. *Note What Is a Function::.
-
-ARRAY
- 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 *Note Keyboard Macros::, for more
- information. (Note that you cannot use a shortened form of a key
- sequence here, such as `(control y)'; you must use the full form
- `[(control y)]'. *Note Key Sequences::.)
-
-LIST
- The meaning of a list depends on the types of the elements of the
- list.
-
- * If the CAR of LIST is `lambda', then the list is a lambda
- expression. This is presumed to be a command, and is treated
- as such (see above).
-
- * If the CAR of LIST is a keymap and the CDR is an event type,
- then this is an "indirect entry":
-
- (OTHERMAP . OTHERTYPE)
-
- When key lookup encounters an indirect entry, it looks up
- instead the binding of OTHERTYPE in OTHERMAP and uses that.
-
- This feature permits you to define one key as an alias for
- another key. For example, an entry whose CAR is the keymap
- called `esc-map' and whose CDR is 32 (the code for <SPC>)
- means, "Use the global binding of `Meta-<SPC>', whatever that
- may be."
-
-SYMBOL
- The function definition of SYMBOL is used in place of SYMBOL. If
- that too is a symbol, then this process is repeated, any number of
- times. Ultimately this should lead to an object that is a keymap,
- a command or a keyboard macro. A list is allowed if it is a
- keymap or a command, but indirect entries are not understood when
- found via symbols.
-
- Note that keymaps and keyboard macros (strings and vectors) are not
- valid functions, so a symbol with a keymap, string, or vector as
- its function definition is invalid as a function. It is, however,
- valid as a key binding. If the definition is a keyboard macro,
- then the symbol is also valid as an argument to `command-execute'
- (*note Interactive Call::.).
-
- The symbol `undefined' is worth special mention: it means to treat
- the key as undefined. Strictly speaking, the key is defined, and
- its binding is the command `undefined'; but that command does the
- same thing that is done automatically for an undefined key: it
- rings the bell (by calling `ding') but does not signal an error.
-
- `undefined' is used in local keymaps to override a global key
- binding and make the key "undefined" locally. A local binding of
- `nil' would fail to do this because it would not override the
- global binding.
-
-ANYTHING ELSE
- If any other type of object is found, the events used so far in the
- lookup form a complete key, and the object is its binding, but the
- binding is not executable as a command.
-
- In short, a keymap entry may be a keymap, a command, a keyboard
-macro, a symbol that leads to one of them, or an indirection or `nil'.
-
-\1f
-File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps
-
-Functions for Key Lookup
-========================
-
- Here are the functions and variables pertaining to key lookup.
-
- - Function: lookup-key KEYMAP KEY &optional ACCEPT-DEFAULTS
- This function returns the definition of KEY in KEYMAP. If the
- string or vector KEY is not a valid key sequence according to the
- prefix keys specified in KEYMAP (which means it is "too long" and
- has extra events at the end), then the value is a number, the
- number of events at the front of KEY that compose a complete key.
-
- If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
- default bindings as well as bindings for the specific events in
- KEY. Otherwise, `lookup-key' reports only bindings for the
- specific sequence KEY, ignoring default bindings except when you
- explicitly ask about them.
-
- All the other functions described in this chapter that look up
- keys use `lookup-key'.
-
- (lookup-key (current-global-map) "\C-x\C-f")
- => find-file
- (lookup-key (current-global-map) "\C-x\C-f12345")
- => 2
-
- If KEY begins with the character whose value is contained in
- `meta-prefix-char', that character is implicitly removed and the
- <META> modifier added to the key. Thus, the first example below is
- handled by conversion into the second example.
-
- (lookup-key (current-global-map) "\ef")
- => forward-word
- (lookup-key (current-global-map) "\M-f")
- => forward-word
-
- Unlike `read-key-sequence', this function does not modify the
- specified events in ways that discard information (*note Key
- Sequence Input::.). In particular, it does not convert letters to
- lower case.
-
- - Command: undefined
- Used in keymaps to undefine keys. If a key sequence is defined to
- this, invoking this key sequence causes a "key undefined" error,
- just as if the key sequence had no binding.
-
- - Function: key-binding KEY &optional ACCEPT-DEFAULTS
- This function returns the binding for KEY in the current keymaps,
- trying all the active keymaps. The result is `nil' if KEY is
- undefined in the keymaps.
-
- The argument ACCEPT-DEFAULTS controls checking for default
- bindings, as in `lookup-key' (above).
-
- (key-binding "\C-x\C-f")
- => find-file
- (key-binding '(control home))
- => beginning-of-buffer
- (key-binding [escape escape escape])
- => keyboard-escape-quit
-
- - Function: local-key-binding KEY &optional ACCEPT-DEFAULTS
- This function returns the binding for KEY in the current local
- keymap, or `nil' if it is undefined there.
-
- The argument ACCEPT-DEFAULTS controls checking for default
- bindings, as in `lookup-key' (above).
-
- - Function: global-key-binding KEY &optional ACCEPT-DEFAULTS
- This function returns the binding for command KEY in the current
- global keymap, or `nil' if it is undefined there.
-
- The argument ACCEPT-DEFAULTS controls checking for default
- bindings, as in `lookup-key' (above).
-
- - Function: minor-mode-key-binding KEY &optional ACCEPT-DEFAULTS
- This function returns a list of all the active minor mode bindings
- of KEY. More precisely, it returns an alist of pairs `(MODENAME .
- BINDING)', where MODENAME is the variable that enables the minor
- mode, and BINDING is KEY's binding in that mode. If KEY has no
- minor-mode bindings, the value is `nil'.
-
- If the first binding is not a prefix command, all subsequent
- bindings from other minor modes are omitted, since they would be
- completely shadowed. Similarly, the list omits non-prefix
- bindings that follow prefix bindings.
-
- The argument ACCEPT-DEFAULTS controls checking for default
- bindings, as in `lookup-key' (above).
-
- - Variable: meta-prefix-char
- This variable is the meta-prefix character code. It is used when
- translating a two-character sequence to a meta character so it can
- be looked up in a keymap. For useful results, the value should be
- a prefix event (*note Prefix Keys::.). The default value is
- `?\^[' (integer 27), which is the ASCII character usually produced
- by the <ESC> key.
-
- As long as the value of `meta-prefix-char' remains `?\^[', key
- lookup translates `<ESC> b' into `M-b', which is normally defined
- as the `backward-word' command. However, if you set
- `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
- equivalent ASCII code `24', then XEmacs will translate `C-x b'
- (whose standard binding is the `switch-to-buffer' command) into
- `M-b'.
-
- meta-prefix-char ; The default value.
- => ?\^[ ; Under XEmacs 20.
- => 27 ; Under XEmacs 19.
-
- (key-binding "\eb")
- => backward-word
-
- ?\C-x ; The print representation
- ; of a character.
- => ?\^X ; Under XEmacs 20.
- => 24 ; Under XEmacs 19.
-
- (setq meta-prefix-char 24)
- => 24
-
- (key-binding "\C-xb")
- => backward-word ; Now, typing `C-x b' is
- ; like typing `M-b'.
-
- (setq meta-prefix-char ?\e) ; Avoid confusion!
- ; Restore the default value!
- => ?\^[ ; Under XEmacs 20.
- => 27 ; Under XEmacs 19.
-
-\1f
-File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps
-
-Changing Key Bindings
-=====================
-
- The way to rebind a key is to change its entry in a keymap. If you
-change a binding in the global keymap, the change is effective in all
-buffers (though it has no direct effect in buffers that shadow the
-global binding with a local one). If you change the current buffer's
-local map, that usually affects all buffers using the same major mode.
-The `global-set-key' and `local-set-key' functions are convenient
-interfaces for these operations (*note Key Binding Commands::.). You
-can also use `define-key', a more general function; then you must
-specify explicitly the map to change.
-
- The way to specify the key sequence that you want to rebind is
-described above (*note Key Sequences::.).
-
- For the functions below, an error is signaled if KEYMAP is not a
-keymap or if KEY is not a string or vector representing a key sequence.
-You can use event types (symbols) as shorthand for events that are
-lists.
-
- - Function: define-key KEYMAP KEY BINDING
- This function sets the binding for KEY in KEYMAP. (If KEY is more
- than one event long, the change is actually made in another keymap
- reached from KEYMAP.) The argument BINDING can be any Lisp
- object, but only certain types are meaningful. (For a list of
- meaningful types, see *Note Key Lookup::.) The value returned by
- `define-key' is BINDING.
-
- Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
- or undefined; otherwise an error is signaled.
-
- If some prefix of KEY is undefined, then `define-key' defines it
- as a prefix key so that the rest of KEY may be defined as
- specified.
-
- Here is an example that creates a sparse keymap and makes a number of
-bindings in it:
-
- (setq map (make-sparse-keymap))
- => #<keymap 0 entries 0xbee>
-
- (define-key map "\C-f" 'forward-char)
- => forward-char
-
- map
- => #<keymap 1 entry 0xbee>
- (describe-bindings-internal map)
- => ; (Inserted in buffer)
- C-f forward-char
-
- ;; Build sparse submap for `C-x' and bind `f' in that.
- (define-key map "\C-xf" 'forward-word)
- => forward-word
-
- map
- => #<keymap 2 entries 0xbee>
- (describe-bindings-internal map)
- => ; (Inserted in buffer)
- C-f forward-char
- C-x << Prefix Command >>
-
- C-x f forward-word
-
- ;; Bind `C-p' to the `ctl-x-map'.
- (define-key map "\C-p" ctl-x-map)
- ;; `ctl-x-map'
- => #<keymap Control-X-prefix 77 entries 0x3bf>
-
- ;; Bind `C-f' to `foo' in the `ctl-x-map'.
- (define-key map "\C-p\C-f" 'foo)
- => foo
-
- map
- => #<keymap 3 entries 0xbee>
- (describe-bindings-internal map)
- => ; (Inserted in buffer)
- C-f forward-char
- C-p << Prefix command Control-X-prefix >>
- C-x << Prefix Command >>
-
- C-p tab indent-rigidly
- C-p $ set-selective-display
- C-p ' expand-abbrev
- C-p ( start-kbd-macro
- C-p ) end-kbd-macro
- ...
- C-p C-x exchange-point-and-mark
- C-p C-z suspend-or-iconify-emacs
- C-p M-escape repeat-complex-command
- C-p M-C-[ repeat-complex-command
-
- C-x f forward-word
-
- C-p 4 . find-tag-other-window
- ...
- C-p 4 C-o display-buffer
-
- C-p 5 0 delete-frame
- ...
- C-p 5 C-f find-file-other-frame
-
- ...
-
- C-p a i g inverse-add-global-abbrev
- C-p a i l inverse-add-mode-abbrev
-
-Note that storing a new binding for `C-p C-f' actually works by
-changing an entry in `ctl-x-map', and this has the effect of changing
-the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
-
- - Function: substitute-key-definition OLDDEF NEWDEF KEYMAP &optional
- OLDMAP
- This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
- that were bound to OLDDEF. In other words, OLDDEF is replaced
- with NEWDEF wherever it appears. The function returns `nil'.
-
- For example, this redefines `C-x C-f', if you do it in an XEmacs
- with standard bindings:
-
- (substitute-key-definition
- 'find-file 'find-file-read-only (current-global-map))
-
- If OLDMAP is non-`nil', then its bindings determine which keys to
- rebind. The rebindings still happen in NEWMAP, not in OLDMAP.
- Thus, you can change one map under the control of the bindings in
- another. For example,
-
- (substitute-key-definition
- 'delete-backward-char 'my-funny-delete
- my-map global-map)
-
- puts the special deletion command in `my-map' for whichever keys
- are globally bound to the standard deletion command.
-
-
- - Function: suppress-keymap KEYMAP &optional NODIGITS
- This function changes the contents of the full keymap KEYMAP by
- making all the printing characters undefined. More precisely, it
- binds them to the command `undefined'. This makes ordinary
- insertion of text impossible. `suppress-keymap' returns `nil'.
-
- If NODIGITS is `nil', then `suppress-keymap' defines digits to run
- `digit-argument', and `-' to run `negative-argument'. Otherwise
- it makes them undefined like the rest of the printing characters.
-
- The `suppress-keymap' function does not make it impossible to
- modify a buffer, as it does not suppress commands such as `yank'
- and `quoted-insert'. To prevent any modification of a buffer, make
- it read-only (*note Read Only Buffers::.).
-
- Since this function modifies KEYMAP, you would normally use it on
- a newly created keymap. Operating on an existing keymap that is
- used for some other purpose is likely to cause trouble; for
- example, suppressing `global-map' would make it impossible to use
- most of XEmacs.
-
- Most often, `suppress-keymap' is used to initialize local keymaps
- of modes such as Rmail and Dired where insertion of text is not
- desirable and the buffer is read-only. Here is an example taken
- from the file `emacs/lisp/dired.el', showing how the local keymap
- for Dired mode is set up:
-
- ...
- (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)
- ...
-
-\1f
-File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps
-
-Commands for Binding Keys
-=========================
-
- This section describes some convenient interactive interfaces for
-changing key bindings. They work by calling `define-key'.
-
- People often use `global-set-key' in their `.emacs' file for simple
-customization. For example,
-
- (global-set-key "\C-x\C-\\" 'next-line)
-
-or
-
- (global-set-key [(control ?x) (control ?\\)] 'next-line)
-
-or
-
- (global-set-key [?\C-x ?\C-\\] 'next-line)
-
-redefines `C-x C-\' to move down a line.
-
- (global-set-key [(meta button1)] 'mouse-set-point)
-
-redefines the first (leftmost) mouse button, typed with the Meta key, to
-set point where you click.
-
- - Command: global-set-key KEY DEFINITION
- This function sets the binding of KEY in the current global map to
- DEFINITION.
-
- (global-set-key KEY DEFINITION)
- ==
- (define-key (current-global-map) KEY DEFINITION)
-
- - Command: global-unset-key KEY
- This function removes the binding of KEY from the current global
- map.
-
- One use of this function is in preparation for defining a longer
- key that uses KEY as a prefix--which would not be allowed if KEY
- has a non-prefix binding. For example:
-
- (global-unset-key "\C-l")
- => nil
-
- (global-set-key "\C-l\C-l" 'redraw-display)
- => nil
-
- This function is implemented simply using `define-key':
-
- (global-unset-key KEY)
- ==
- (define-key (current-global-map) KEY nil)
-
- - Command: local-set-key KEY DEFINITION
- This function sets the binding of KEY in the current local keymap
- to DEFINITION.
-
- (local-set-key KEY DEFINITION)
- ==
- (define-key (current-local-map) KEY DEFINITION)
-
- - Command: local-unset-key KEY
- This function removes the binding of KEY from the current local
- map.
-
- (local-unset-key KEY)
- ==
- (define-key (current-local-map) KEY nil)
-
-\1f
-File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps
-
-Scanning Keymaps
-================
-
- This section describes functions used to scan all the current
-keymaps, or all keys within a keymap, for the sake of printing help
-information.
-
- - Function: accessible-keymaps KEYMAP &optional PREFIX
- This function returns a list of all the keymaps that can be
- accessed (via prefix keys) from KEYMAP. The value is an
- association list with elements of the form `(KEY . MAP)', where
- KEY is a prefix key whose definition in KEYMAP is MAP.
-
- The elements of the alist are ordered so that the KEY increases in
- length. The first element is always `([] . KEYMAP)', because the
- specified keymap is accessible from itself with a prefix of no
- events.
-
- If PREFIX is given, it should be a prefix key sequence; then
- `accessible-keymaps' includes only the submaps whose prefixes start
- with PREFIX. These elements look just as they do in the value of
- `(accessible-keymaps)'; the only difference is that some elements
- are omitted.
-
- In the example below, the returned alist indicates that the key
- `C-x', which is displayed as `[(control x)]', is a prefix key
- whose definition is the keymap `#<keymap ((control x) #<keymap
- emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
- notation for the keymap's name indicates that this is an internal
- submap of `emacs-lisp-mode-map'. This is because
- `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
- its parent, and `lisp-interaction-mode-map' defines no key
- sequences beginning with `C-x'.)
-
- (current-local-map)
- => #<keymap lisp-interaction-mode-map 5 entries 0x558>
- (accessible-keymaps (current-local-map))
- =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
- ([(control x)] .
- #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
- 1 entry 0x8a2>))
-
- The following example shows the results of calling
- `accessible-keymaps' on a large, complex keymap. Notice how some
- keymaps were given explicit names using `set-keymap-name'; those
- submaps without explicit names are given descriptive names
- indicating their relationship to their enclosing keymap.
-
- (accessible-keymaps (current-global-map))
- => (([] . #<keymap global-map 639 entries 0x221>)
- ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
- ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
- ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
- ([(meta escape)] .
- #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
- 3 entries 0x3e0>)
- ([(meta control \[)] .
- #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
- 3 entries 0x3e0>)
- ([f1] . #<keymap help-map 33 entries 0x4ec>)
- ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
- ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
- ([(control x) \6] . #<keymap 13 entries 0x4d2>)
- ([(control x) a] .
- #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
- 8 entries 0x3ef>)
- ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
- ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
- ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
- ([(control x) a i] .
- #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
- 8 entries 0x3ef>)
- 2 entries 0x3f5>))
-
- - Function: map-keymap FUNCTION KEYMAP &optional SORT-FIRST
- This function applies FUNCTION to each element of `KEYMAP'.
- FUNCTION will be called with two arguments: a key-description
- list, and the binding. The order in which the elements of the
- keymap are passed to the function is unspecified. If the function
- inserts new elements into the keymap, it may or may not be called
- with them later. No element of the keymap will ever be passed to
- the function more than once.
-
- The function will not be called on elements of this keymap's
- parents (*note Inheritance and Keymaps::.) or upon keymaps which
- are contained within this keymap (multi-character definitions).
- It will be called on <META> characters since they are not really
- two-character sequences.
-
- If the optional third argument SORT-FIRST is non-`nil', then the
- elements of the keymap will be passed to the mapper function in a
- canonical order. Otherwise, they will be passed in hash (that is,
- random) order, which is faster.
-
- - Function: keymap-fullness KEYMAP
- This function returns the number of bindings in the keymap.
-
- - Function: where-is-internal DEFINITION &optional KEYMAPS FIRSTONLY
- NOINDIRECT EVENT-OR-KEYS
- This function returns a list of key sequences (of any length) that
- are bound to DEFINITION in a set of keymaps.
-
- The argument DEFINITION can be any object; it is compared with all
- keymap entries using `eq'.
-
- KEYMAPS can be either a keymap (meaning search in that keymap and
- the current global keymap) or a list of keymaps (meaning search in
- exactly those keymaps and no others). If KEYMAPS is nil, search
- in the currently applicable maps for EVENT-OR-KEYS.
-
- If KEYMAP is a keymap, then the maps searched are KEYMAP and the
- global keymap. If KEYMAP is a list of keymaps, then the maps
- searched are exactly those keymaps, and no others. If KEYMAP is
- `nil', then the maps used are the current active keymaps for
- EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
- EVENT-OR-KEYS)' as the argument to KEYMAPS).
-
- If FIRSTONLY is non-`nil', then the value is a single vector
- representing the first key sequence found, rather than a list of
- all possible key sequences.
-
- If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
- indirect keymap bindings. This makes it possible to search for an
- indirect definition itself.
-
- This function is used by `where-is' (*note Help: (emacs)Help.).
-
- (where-is-internal 'describe-function)
- => ([(control h) d] [(control h) f] [f1 d] [f1 f])
-
- - Function: describe-bindings-internal MAP &optional ALL SHADOW PREFIX
- MOUSE-ONLY-P
- This function inserts (into the current buffer) a list of all
- defined keys and their definitions in MAP. Optional second
- argument ALL says whether to include even "uninteresting"
- definitions, i.e. symbols with a non-`nil' `suppress-keymap'
- property. Third argument SHADOW is a list of keymaps whose
- bindings shadow those of map; if a binding is present in any
- shadowing map, it is not printed. Fourth argument PREFIX, if
- non-`nil', should be a key sequence; only bindings which start
- with that key sequence will be printed. Fifth argument
- MOUSE-ONLY-P says to only print bindings for mouse clicks.
-
- `describe-bindings-internal' is used to implement the help command
-`describe-bindings'.
-
- - Command: describe-bindings PREFIX MOUSE-ONLY-P
- This function creates a listing of all defined keys and their
- definitions. It writes the listing in a buffer named `*Help*' and
- displays it in a window.
-
- If PREFIX is non-`nil', it should be a prefix key; then the
- listing includes only keys that start with PREFIX.
-
- When several characters with consecutive ASCII codes have the same
- definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In
- this instance, you need to know the ASCII codes to understand
- which characters this means. For example, in the default global
- map, the characters `<SPC> .. ~' are described by a single line.
- <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
- them include all the normal printing characters, (e.g., letters,
- digits, punctuation, etc.); all these characters are bound to
- `self-insert-command'.
-
- If the second argument (prefix arg, interactively) is non-`nil'
- then only the mouse bindings are displayed.
-
-\1f
-File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps
-
-Other Keymap Functions
-======================
-
- - Function: set-keymap-prompt KEYMAP NEW-PROMPT
- This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
- `nil' if no prompt is desired. The prompt is shown in the
- echo-area when reading a key-sequence to be looked-up in this
- keymap.
-
- - Function: keymap-prompt KEYMAP &optional USE-INHERITED
- This function returns the "prompt" of the given keymap. If
- USE-INHERITED is non-`nil', any parent keymaps will also be
- searched for a prompt.
-
-\1f
-File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top
-
-Menus
-*****
-
-* Menu:
-
-* Menu Format:: Format of a menu description.
-* Menubar Format:: How to specify a menubar.
-* Menubar:: Functions for controlling the menubar.
-* Modifying Menus:: Modifying a menu description.
-* Pop-Up Menus:: Functions for specifying pop-up menus.
-* Menu Filters:: Filter functions for the default menubar.
-* Menu Accelerators:: Using and controlling menu accelerator keys
-* Buffers Menu:: The menu that displays the list of buffers.
-
-\1f
-File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
-
-Format of Menus
-===============
-
- A menu is described using a "menu description", which is a list of
-menu items, keyword-value pairs, strings, and submenus. The menu
-description specifies which items are present in the menu, what function
-each item invokes, and whether the item is selectable or not. Pop-up
-menus are directly described with a menu description, while menubars are
-described slightly differently (see below).
-
- The first element of a menu must be a string, which is the name of
-the menu. This is the string that will be displayed in the parent menu
-or menubar, if any. This string is not displayed in the menu itself,
-except in the case of the top level pop-up menu, where there is no
-parent. In this case, the string will be displayed at the top of the
-menu if `popup-menu-titles' is non-`nil'.
-
- Immediately following the first element there may optionally be up
-to four keyword-value pairs, as follows:
-
-`:included FORM'
- This can be used to control the visibility of a menu. The form is
- evaluated and the menu will be omitted if the result is `nil'.
-
-`:config SYMBOL'
- This is an efficient shorthand for `:included (memq SYMBOL
- menubar-configuration)'. See the variable `menubar-configuration'.
-
-`:filter FUNCTION'
- A menu filter is used to sensitize or incrementally create a
- submenu only when it is selected by the user and not every time
- the menubar is activated. The filter function is passed the list
- of menu items in the submenu and must return a list of menu items
- to be used for the menu. It is called only when the menu is about
- to be displayed, so other menus may already be displayed. Vile
- and terrible things will happen if a menu filter function changes
- the current buffer, window, or frame. It also should not raise,
- lower, or iconify any frames. Basically, the filter function
- should have no side-effects.
-
-`:accelerator KEY'
- A menu accelerator is a keystroke which can be pressed while the
- menu is visible which will immediately activate the item. KEY
- must be a char or the symbol name of a key. *Note Menu
- Accelerators::.
-
- The rest of the menu consists of elements as follows:
-
- * A "menu item", which is a vector in the following form:
-
- `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
-
- NAME is a string, the name of the menu item; it is the string to
- display on the menu. It is filtered through the resource
- database, so it is possible for resources to override what string
- is actually displayed.
-
- CALLBACK is a form that will be invoked when the menu item is
- selected. If the callback of a menu item is a symbol, then it
- must name a command. It will be invoked with
- `call-interactively'. If it is a list, then it is evaluated with
- `eval'.
-
- The valid keywords and their meanings are described below.
-
- Note that for compatibility purposes, the form
-
- `[ NAME CALLBACK ACTIVE-P ]'
-
- is also accepted and is equivalent to
-
- `[ NAME CALLBACK :active ACTIVE-P ]'
-
- and the form
-
- `[ NAME CALLBACK ACTIVE-P SUFFIX]'
-
- is accepted and is equivalent to
-
- `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
-
- However, these older forms are deprecated and should generally not
- be used.
-
- * If an element of a menu is a string, then that string will be
- presented in the menu as unselectable text.
-
- * If an element of a menu is a string consisting solely of hyphens,
- then that item will be presented as a solid horizontal line.
-
- * If an element of a menu is a string beginning with `--:', then a
- particular sort of horizontal line will be displayed, as follows:
-
- `"--:singleLine"'
- A solid horizontal line. This is equivalent to a string
- consisting solely of hyphens.
-
- `"--:doubleLine"'
- A solid double horizontal line.
-
- `"--:singleDashedLine"'
- A dashed horizontal line.
-
- `"--:doubleDashedLine"'
- A dashed double horizontal line.
-
- `"--:noLine"'
- No line (but a small space is left).
-
- `"--:shadowEtchedIn"'
- A solid horizontal line with a 3-d recessed appearance.
-
- `"--:shadowEtchedOut"'
- A solid horizontal line with a 3-d pushed-out appearance.
-
- `"--:shadowDoubleEtchedIn"'
- A solid double horizontal line with a 3-d recessed appearance.
-
- `"--:shadowDoubleEtchedOut"'
- A solid double horizontal line with a 3-d pushed-out
- appearance.
-
- `"--:shadowEtchedInDash"'
- A dashed horizontal line with a 3-d recessed appearance.
-
- `"--:shadowEtchedOutDash"'
- A dashed horizontal line with a 3-d pushed-out appearance.
-
- `"--:shadowDoubleEtchedInDash"'
- A dashed double horizontal line with a 3-d recessed
- appearance.
-
- `"--:shadowDoubleEtchedOutDash"'
- A dashed double horizontal line with a 3-d pushed-out
- appearance.
-
- * If an element of a menu is a list, it is treated as a submenu.
- The name of that submenu (the first element in the list) will be
- used as the name of the item representing this menu on the parent.
-
- The possible keywords are as follows:
-
-:active FORM
- FORM will be evaluated when the menu that this item is a part of
- is about to be displayed, and the item will be selectable only if
- the result is non-`nil'. If the item is unselectable, it will
- usually be displayed grayed-out to indicate this.
-
-:suffix FORM
- FORM will be evaluated when the menu that this item is a part of
- is about to be displayed, and the resulting string is appended to
- the displayed name. This provides a convenient way of adding the
- name of a command's "argument" to the menu, like `Kill Buffer
- NAME'.
-
-:keys STRING
- Normally, the keyboard equivalents of commands in menus are
- displayed when the "callback" is a symbol. This can be used to
- specify keys for more complex menu items. It is passed through
- `substitute-command-keys' first.
-
-:style STYLE
- Specifies what kind of object this menu item is. STYLE be one of
- the symbols
-
- `nil'
- A normal menu item.
-
- `toggle'
- A toggle button.
-
- `radio'
- A radio button.
-
- `button'
- A menubar button.
-
- The only difference between toggle and radio buttons is how they
- are displayed. But for consistency, a toggle button should be
- used when there is one option whose value can be turned on or off,
- and radio buttons should be used when there is a set of mutually
- exclusive options. When using a group of radio buttons, you
- should arrange for no more than one to be marked as selected at a
- time.
-
-:selected FORM
- Meaningful only when STYLE is `toggle', `radio' or `button'. This
- specifies whether the button will be in the selected or unselected
- state. FORM is evaluated, as for `:active'.
-
-:included FORM
- This can be used to control the visibility of a menu item. The
- form is evaluated and the menu item is only displayed if the
- result is non-`nil'. Note that this is different from `:active':
- If `:active' evaluates to `nil', the item will be displayed grayed
- out, while if `:included' evaluates to `nil', the item will be
- omitted entirely.
-
-:config SYMBOL
- This is an efficient shorthand for `:included (memq SYMBOL
- menubar-configuration)'. See the variable `menubar-configuration'.
-
-:accelerator KEY
- A menu accelerator is a keystroke which can be pressed while the
- menu is visible which will immediately activate the item. KEY
- must be a char or the symbol name of a key. *Note Menu
- Accelerators::.
-
- - Variable: menubar-configuration
- This variable holds a list of symbols, against which the value of
- the `:config' tag for each menubar item will be compared. If a
- menubar item has a `:config' tag, then it is omitted from the
- menubar if that tag is not a member of the `menubar-configuration'
- list.
-
- For example:
-
- ("File"
- :filter file-menu-filter ; file-menu-filter is a function that takes
- ; one argument (a list of menu items) and
- ; returns a list of menu items
- [ "Save As..." write-file]
- [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
- [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ]
- )
-
-\1f
-File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
-
-Format of the Menubar
-=====================
-
- A menubar is a list of menus, menu items, and strings. The format is
-similar to that of a menu, except:
-
- * The first item need not be a string, and is not treated specially.
-
- * A string consisting solely of hyphens is not treated specially.
-
- * If an element of a menubar is `nil', then it is used to represent
- the division between the set of menubar items which are flush-left
- and those which are flush-right. (Note: this isn't completely
- implemented yet.)
-
-\1f
-File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
-
-Menubar
-=======
-
- - Variable: current-menubar
- This variable holds the description of the current menubar. This
- may be buffer-local. When the menubar is changed, the function
- `set-menubar-dirty-flag' has to be called in order for the menubar
- to be updated on the screen.
-
- - Constant: default-menubar
- This variable holds the menubar description of the menubar that is
- visible at startup. This is the value that `current-menubar' has
- at startup.
-
- - Function: set-menubar-dirty-flag
- This function tells XEmacs that the menubar widget has to be
- updated. Changes to the menubar will generally not be visible
- until this function is called.
-
- The following convenience functions are provided for setting the
-menubar. They are equivalent to doing the appropriate action to change
-`current-menubar', and then calling `set-menubar-dirty-flag'. Note
-that these functions copy their argument using `copy-sequence'.
-
- - Function: set-menubar MENUBAR
- This function sets the default menubar to be MENUBAR (*note Menu
- Format::.). This is the menubar that will be visible in buffers
- that have not defined their own, buffer-local menubar.
-
- - Function: set-buffer-menubar MENUBAR
- This function sets the buffer-local menubar to be MENUBAR. This
- does not change the menubar in any buffers other than the current
- one.
-
- Miscellaneous:
-
- - Variable: menubar-show-keybindings
- If true, the menubar will display keyboard equivalents. If false,
- only the command names will be displayed.
-
- - Variable: activate-menubar-hook
- Function or functions called before a menubar menu is pulled down.
- These functions are called with no arguments, and should
- interrogate and modify the value of `current-menubar' as desired.
-
- The functions on this hook are invoked after the mouse goes down,
- but before the menu is mapped, and may be used to activate,
- deactivate, add, or delete items from the menus. However, using a
- filter (with the `:filter' keyword in a menu description) is
- generally a more efficient way of accomplishing the same thing,
- because the filter is invoked only when the actual menu goes down.
- With a complex menu, there can be a quite noticeable and
- sometimes aggravating delay if all menu modification is
- implemented using the `activate-menubar-hook'. See above.
-
- These functions may return the symbol `t' to assert that they have
- made no changes to the menubar. If any other value is returned,
- the menubar is recomputed. If `t' is returned but the menubar has
- been changed, then the changes may not show up right away.
- Returning `nil' when the menubar has not changed is not so bad;
- more computation will be done, but redisplay of the menubar will
- still be performed optimally.
-
- - Variable: menu-no-selection-hook
- Function or functions to call when a menu or dialog box is
- dismissed without a selection having been made.
-
-\1f
-File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
-
-Modifying Menus
-===============
-
- The following functions are provided to modify the menubar of one of
-its submenus. Note that these functions modify the menu in-place,
-rather than copying it and making a new menu.
-
- Some of these functions take a "menu path", which is a list of
-strings identifying the menu to be modified. For example, `("File")'
-names the top-level "File" menu. `("File" "Foo")' names a hypothetical
-submenu of "File".
-
- Others take a "menu item path", which is similar to a menu path but
-also specifies a particular item to be modified. For example, `("File"
-"Save")' means the menu item called "Save" under the top-level "File"
-menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
-the "Foo" submenu of "Menu".
-
- - Function: add-submenu MENU-PATH SUBMENU &optional BEFORE
- This function adds a menu to the menubar or one of its submenus.
- If the named menu exists already, it is changed.
-
- MENU-PATH identifies the menu under which the new menu should be
- inserted. If MENU-PATH is `nil', then the menu will be added to
- the menubar itself.
-
- SUBMENU is the new menu to add (*note Menu Format::.).
-
- BEFORE, if provided, is the name of a menu before which this menu
- should be added, if this menu is not on its parent already. If
- the menu is already present, it will not be moved.
-
- - Function: add-menu-button MENU-PATH MENU-LEAF &optional BEFORE
- This function adds a menu item to some menu, creating the menu
- first if necessary. If the named item exists already, it is
- changed.
-
- MENU-PATH identifies the menu under which the new menu item should
- be inserted.
-
- MENU-LEAF is a menubar leaf node (*note Menu Format::.).
-
- BEFORE, if provided, is the name of a menu before which this item
- should be added, if this item is not on the menu already. If the
- item is already present, it will not be moved.
-
- - Function: delete-menu-item MENU-ITEM-PATH
- This function removes the menu item specified by MENU-ITEM-PATH
- from the menu hierarchy.
-
- - Function: enable-menu-item MENU-ITEM-PATH
- This function makes the menu item specified by MENU-ITEM-PATH be
- selectable.
-
- - Function: disable-menu-item MENU-ITEM-PATH
- This function makes the menu item specified by MENU-ITEM-PATH be
- unselectable.
-
- - Function: relabel-menu-item MENU-ITEM-PATH NEW-NAME
- This function changes the string of the menu item specified by
- MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
- printed as from now on.
-
- The following function can be used to search for a particular item in
-a menubar specification, given a path to the item.
-
- - Function: find-menu-item MENUBAR MENU-ITEM-PATH &optional PARENT
- This function searches MENUBAR for the item given by
- MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
- of MENUBAR). This function returns `(ITEM . PARENT)', where
- PARENT is the immediate parent of the item found (a menu
- description), and ITEM is either a vector, list, or string,
- depending on the nature of the menu item.
-
- This function signals an error if the item is not found.
-
- The following deprecated functions are also documented, so that
-existing code can be understood. You should not use these functions in
-new code.
-
- - Function: add-menu MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE
- This function adds a menu to the menubar or one of its submenus.
- If the named menu exists already, it is changed. This is
- obsolete; use `add-submenu' instead.
-
- MENU-PATH identifies the menu under which the new menu should be
- inserted. If MENU-PATH is `nil', then the menu will be added to
- the menubar itself.
-
- MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
- a list of menu items, strings, and submenus. These two arguments
- are the same as the first and following elements of a menu
- description (*note Menu Format::.).
-
- BEFORE, if provided, is the name of a menu before which this menu
- should be added, if this menu is not on its parent already. If the
- menu is already present, it will not be moved.
-
- - Function: add-menu-item MENU-PATH ITEM-NAME FUNCTION ENABLED-P
- &optional BEFORE
- This function adds a menu item to some menu, creating the menu
- first if necessary. If the named item exists already, it is
- changed. This is obsolete; use `add-menu-button' instead.
-
- MENU-PATH identifies the menu under which the new menu item should
- be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
- second, and third elements of a menu item vector (*note Menu
- Format::.).
-
- BEFORE, if provided, is the name of a menu item before which this
- item should be added, if this item is not on the menu already. If
- the item is already present, it will not be moved.
-
-\1f
-File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
-
-Menu Filters
-============
-
- The following filter functions are provided for use in
-`default-menubar'. You may want to use them in your own menubar
-description.
-
- - Function: file-menu-filter MENU-ITEMS
- This function changes the arguments and sensitivity of these File
- menu items:
-
- `Delete Buffer'
- Has the name of the current buffer appended to it.
-
- `Print Buffer'
- Has the name of the current buffer appended to it.
-
- `Pretty-Print Buffer'
- Has the name of the current buffer appended to it.
-
- `Save Buffer'
- Has the name of the current buffer appended to it, and is
- sensitive only when the current buffer is modified.
-
- `Revert Buffer'
- Has the name of the current buffer appended to it, and is
- sensitive only when the current buffer has a file.
-
- `Delete Frame'
- Sensitive only when there is more than one visible frame.
-
- - Function: edit-menu-filter MENU-ITEMS
- This function changes the arguments and sensitivity of these Edit
- menu items:
-
- `Cut'
- Sensitive only when XEmacs owns the primary X Selection (if
- `zmacs-regions' is `t', this is equivalent to saying that
- there is a region selected).
-
- `Copy'
- Sensitive only when XEmacs owns the primary X Selection.
-
- `Clear'
- Sensitive only when XEmacs owns the primary X Selection.
-
- `Paste'
- Sensitive only when there is an owner for the X Clipboard
- Selection.
-
- `Undo'
- Sensitive only when there is undo information. While in the
- midst of an undo, this is changed to `Undo More'.
-
- - Function: buffers-menu-filter MENU-ITEMS
- This function sets up the Buffers menu. *Note Buffers Menu::, for
- more information.
-
projects / chise / xemacs-chise.git- / blobdiff