code.delx.au - gnu-emacs-elpa/blob - packages/hydra/README.md

   1 This is a package for GNU Emacs that can be used to tie related
   2 commands into a family of short bindings with a common prefix - a
   3 Hydra.
   4
   5 Once you summon the Hydra through the prefixed binding (the body + any
   6 one head), all heads can be called in succession with only a short
   7 extension.
   8
   9 The Hydra is vanquished once Hercules, any binding that isn't the
  10 Hydra's head, arrives.  Note that Hercules, besides vanquishing the
  11 Hydra, will still serve his orignal purpose, calling his proper
  12 command.  This makes the Hydra very seamless, it's like a minor mode
  13 that disables itself auto-magically.
  14
  15 Here's how I use the examples bundled with Hydra:
  16
  17     (require 'hydra-examples)
  18     (hydra-create "C-M-y" hydra-example-move-window-splitter)
  19     (hydra-create "M-g" hydra-example-goto-error)
  20
  21 You can expand the examples in-place, it still looks elegant:
  22
  23     (hydra-create "<f2>"
  24       '(("g" text-scale-increase)
  25         ("l" text-scale-decrease)))
  26
  27 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
  28
  29 ![hydra](http://oremacs.com/download/Hydra.png)
  30
  31 ## Using Hydra to define bindings other than global ones
  32
  33 You can use the third optional argument of `hydra-create` for this (it defaults to `global-set-key`).
  34 Here's an example:
  35
  36 ```cl
  37 (hydra-create "C-z"
  38   '(("l" forward-char)
  39     ("h" backward-char)
  40     ("j" next-line)
  41     ("k" previous-line))
  42   (lambda (key command)
  43     (define-key lispy-mode-map key command)))
  44 ```
  45
  46 For this simple case, there's even a shortcut: if you give a keymap as the third argument,
  47 the lambda will be generated for you:
  48
  49 ```cl
  50 (hydra-create "C-z"
  51   '(("l" forward-char)
  52     ("h" backward-char)
  53     ("j" next-line)
  54     ("k" previous-line))
  55     lispy-mode-map)
  56 ```
  57
  58 ## Can Hydras can be helpful?
  59
  60 They can, if
  61
  62 ```cl
  63 (setq hydra-is-helpful t)
  64 ```
  65
  66 In that case, you'll get a hint in the echo area consisting of current Hydra's heads.
  67 You can even add comments to the heads like this:
  68
  69 ```
  70 (defvar hydra-example-text-scale
  71   '(("g" text-scale-increase "zoom in")
  72     ("l" text-scale-decrease "zoom out"))
  73   "A two-headed hydra for text scale manipulation.")
  74 ```
  75
  76 With this, you'll see `hydra: [g]: zoom in, [l]: zoom out.` in your
  77 echo area, once the zoom Hydra becomes active.