home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / new / util / edit / jade / man / jade.info-8 (.txt) < prev    next >
GNU Info File  |  1994-10-16  |  50KB  |  977 lines
  1. This is Info file jade.info, produced by Makeinfo-1.55 from the input
  2. file jade.texi.
  3. START-INFO-DIR-ENTRY
  4. * Jade: (jade).            An editor for X11 and AmigaDOS
  5. END-INFO-DIR-ENTRY
  6.    This is Edition 1.3, last updated 7 October 1994, of `The Jade
  7. Manual', for Jade, Version 3.2.
  8.    Jade is a text editor for X11 (on Unix) and the Amiga.
  9.    Copyright 1993, 1994 John Harper.
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.    Permission is granted to copy and distribute modified versions of
  14. this manual under the conditions for verbatim copying, provided that
  15. the entire resulting derived work is distributed under the terms of a
  16. permission notice identical to this one.
  17. File: jade.info,  Node: Keymaps,  Next: Event Loop,  Prev: Input Events,  Up: Programming Jade
  18. Keymaps
  19. =======
  20.    A "keymap" is a Lisp object defining a mapping between input events
  21. (*note Input Events::.) and commands to be executed when the event loop
  22. (*note Event Loop::.) receives the input event.
  23.  - Function: keymapp OBJECT
  24.      Returns `t' when OBJECT is a keymap.
  25. * Menu:
  26. * Types of Keymap::             Two different formats of keymap
  27. * Creating Keymaps::            Allocating new keymaps
  28. * Binding Keys::                Inserting and removing key bindings
  29. * Key Lookup::                  How a key press is resolved into a command
  30. * Prefix Keys::                 Chaining events into multiple-event
  31.                                   bindings
  32. * Standard Keymaps::            Predefined keymaps you can modify
  33. File: jade.info,  Node: Types of Keymap,  Next: Creating Keymaps,  Up: Keymaps
  34. Types of Keymap
  35. ---------------
  36.    There are two different types of keymap; one for keymaps which
  37. contain only a few bindings, the other providing a more efficient
  38. method of storing larger numbers of bindings.
  39. "Key lists"
  40.      These are used for keymaps which only contain a few bindings; they
  41.      are lists whose first element is the symbol `keymap'. All
  42.      subsequent elements define bindings, they are represented by
  43.      three-element vectors. The first two are the contents of the cons
  44.      cell representing the input event, the other element is the
  45.      command to be invoked.
  46.      For example,
  47.           (keymap [120 9 some-command])
  48.      Since the event `(120 . 9)' is the key press `Ctrl-x', this keymap
  49.      binds the command `some-command' to the key press `Ctrl-x'.
  50. "Key tables"
  51.      Key tables are used for keymaps which contain a larger number of
  52.      bindings.  They are vectors of 127 elements, a hash function is
  53.      used to hash each event contained in the keymap into one of the
  54.      127 buckets. Each bucket is a list of key bindings in the same
  55.      form as a key list (but without the `keymap' symbol).
  56. File: jade.info,  Node: Creating Keymaps,  Next: Binding Keys,  Prev: Types of Keymap,  Up: Keymaps
  57. Creating Keymaps
  58. ----------------
  59.    Since there are two different types of keymap (lists and tables)
  60. there are two different functions for creating them with.
  61.  - Function: make-keylist
  62.      Creates and returns a new key list containing no bindings.
  63.           (make-keylist)
  64.               => (keymap)
  65.  - Function: make-keytab
  66.      This function returns a new key table; it will be totally empty.
  67.           (make-keytab)
  68.               => [nil nil ... nil]
  69.    If you want to produce a new copy of a keymap use the `copy-sequence'
  70. function (*note Sequence Functions::.) to duplicate the source keymap.
  71. File: jade.info,  Node: Binding Keys,  Next: Key Lookup,  Prev: Creating Keymaps,  Up: Keymaps
  72. Binding Keys
  73. ------------
  74.    The `bind-keys' function is used to install new key bindings into a
  75. keymap (either a key list or table).
  76.  - Function: bind-keys KEYMAP &rest BINDINGS
  77.      This function installs zero or more key bindings into the keymap
  78.      KEYMAP.
  79.      Each binding is defined by two elements in the list of BINDINGS,
  80.      the first defines the name of the input event (or the event itself)
  81.      and the second defines the command to be associated with the event.
  82.      For example to bind two keys in the keymap KEYMAP; the event
  83.      `Ctrl-f' to the command `goto-next-char' and the event `Ctrl-b' to
  84.      the command `goto-prev-command' the following form would be used,
  85.           (bind-keys KEYMAP
  86.            "Ctrl-f" 'goto-next-char
  87.            "Ctrl-b" 'goto-prev-char)
  88.  - Function: unbind-keys KEYMAP &rest KEYS
  89.      This function removes the bindings of the events KEYS (these may
  90.      be the names of the events or the event objects themselves) from
  91.      the keymap KEYMAP.
  92.           (unbind-keys KEYMAP
  93.            "Ctrl-f"
  94.            "Ctrl-b")
  95. File: jade.info,  Node: Key Lookup,  Next: Prefix Keys,  Prev: Binding Keys,  Up: Keymaps
  96. Key Lookup
  97. ----------
  98.    Each time the event loop (*note Event Loop::.) receives an input
  99. event from the window system it searches for a binding of that event.
  100.    The variables `keymap-path' and `next-keymap-path' are used to
  101. determine the "keymap environment", this is the list of keymaps which
  102. are searched when looking for the binding.
  103.  - Function: lookup-event-binding EVENT &optional RESET-PATH
  104.      This function examines the current keymap environment for a
  105.      binding of the event EVENT (*note Input Events::.). If such a
  106.      binding is found its command is returned, otherwise `nil' is
  107.      returned.
  108.      If the optional RESET-PATH argument is non-`nil' the
  109.      `next-keymap-path' variable will be set to `nil', otherwise it
  110.      will be left with its original value.
  111.  - Variable: keymap-path
  112.      A buffer-local variable providing the list of keymaps (or
  113.      variables whose values are keymaps) which will be searched for a
  114.      binding when the value of the `next-keymap-path' variable is `nil'.
  115.           keymap-path
  116.               => (minor-mode-keymap texinfo-keymap global-keymap)
  117.  - Variable: next-keymap-path
  118.      This variable is used to create multi-event key bindings. When it
  119.      has a non-`nil' value it overrides the `keymap-path' variable when
  120.      a key binding is being searched for.
  121.      After the value of this variable is used to search for a key
  122.      binding it is set to `nil'. This means that, unless another prefix
  123.      key occurred, the next input event received will be resolved
  124.      through the `keymap-path' variable.
  125.      When this variable is set the value of the `prefix-arg' variable is
  126.      set to the current value of the `current-prefix-arg' variable.
  127.      This is so a prefix argument given to a multi-event command is
  128.      transmitted through to the command.
  129.      For more details on multi-event bindings see *Note Prefix Keys::.
  130. File: jade.info,  Node: Prefix Keys,  Next: Standard Keymaps,  Prev: Key Lookup,  Up: Keymaps
  131. Prefix Keys
  132. -----------
  133.    As briefly noted in the previous section it is possible to create
  134. multi-event key bindings. The `next-keymap-path' variable is used to
  135. link key presses (known as "prefix keys" since they prefix the actual,
  136. command-invoking, binding) to a new keymap environment which will be
  137. used to resolve the next key press. This method allows key sequences of
  138. an arbitrary length to be used.
  139.    The best way to explain this is probably with an example. Consider
  140. the following,
  141.      (setq entry-keymap (make-keylist))
  142.      (bind-keys entry-keymap
  143.       "Ctrl-x" '(setq next-keymap-path '(second-keymap)))
  144.      
  145.      (setq second-keymap (make-keylist))
  146.      (bind-keys second-keymap
  147.       "Ctrl-j" 'some-command)
  148. Two keymaps are created, the first of which, `entry-keymap', would be
  149. placed in the `keymap-path' list. When `Ctrl-x' is typed the associated
  150. command would be invoked, installing the next piece of the chain, the
  151. `second-keymap' into the `next-keymap-path' variable.
  152.    So, after `Ctrl-x' is typed the keymap environment will be the list
  153. of keymaps `(second-keymap)', subsequently typing `Ctrl-j' would then
  154. invoke the command `some-command'.
  155. File: jade.info,  Node: Standard Keymaps,  Prev: Prefix Keys,  Up: Keymaps
  156. Standard Keymaps
  157. ----------------
  158.    Several keymaps are predefined by Jade.
  159. `global-keymap'
  160.      This keymap is the root of the global keymap structure; all buffers
  161.      which allow themselves to be edited have th